1 RMOS3 V3.50 Reference Manual Part II ___________________ About this manual... 2 ___________________ Function groups RMOS3 RMOS3 real-time operating system RMOS3 V3.50 Reference Manual Part II Programming Manual 07/2012 A5E03692298-01 3 ___________________ Data structures 4 ___________________ Error codes and messages Functions and configuration 5 ___________________ of the basic I/O system A ___________________ Abbreviations/glossary 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 (R) are registered trademarks of Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner. Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions. Siemens AG Industry Sector Postfach 48 48 90026 NURNBERG GERMANY A5E03692298-01 07/2012 Technical data subject to change Copyright (c) Siemens AG 2012. All rights reserved Table of contents 1 2 3 About this manual... .............................................................................................................................. 11 1.1 About this manual... .....................................................................................................................11 1.2 Notations ......................................................................................................................................12 Function groups .................................................................................................................................... 15 2.1 2.1.1 2.1.2 2.1.3 2.1.4 RMOS3 functions .........................................................................................................................15 Notes on programming in C .........................................................................................................16 Short description of the RMOS3 functions ...................................................................................17 Configuration functions ................................................................................................................23 Miscellaneous functions ...............................................................................................................25 2.2 2.2.1 2.2.2 2.2.3 CLI functions ................................................................................................................................26 Startup code for C programs........................................................................................................26 Problems when aborting a program .............................................................................................26 Short description of the CLI functions ..........................................................................................27 2.3 2.3.1 2.3.2 C library functions ........................................................................................................................28 Scope of the C library ..................................................................................................................28 Short description of the C library functions ..................................................................................28 2.4 2.4.1 2.4.2 2.4.3 2.4.4 Driver functions ............................................................................................................................37 Application model .........................................................................................................................37 Short description of the driver functions ......................................................................................38 System variables for parameter transfer ......................................................................................39 Differences between type I and type II drivers .............................................................................39 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 3 Table of contents 4 5 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 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 Functions and configuration of the basic I/O system .............................................................................. 95 5.1 Overview ..................................................................................................................................... 95 5.2 5.2.1 5.2.1.1 5.2.1.2 5.2.1.3 5.2.1.4 5.2.1.5 5.2.1.6 5.2.1.7 5.2.2 5.2.2.1 5.2.2.2 5.2.2.3 5.2.3 5.2.3.1 5.2.3.2 5.2.3.3 5.2.3.4 5.2.3.5 5.2.3.6 5.2.3.7 5.2.3.8 BYT driver ................................................................................................................................... 96 Properties .................................................................................................................................... 96 Optional EGA functions ............................................................................................................... 97 Half/full duplex mode ................................................................................................................... 97 Control characters for BYT drivers and terminals ....................................................................... 99 History mode ............................................................................................................................. 101 Data flow of received characters ............................................................................................... 101 Special features for EGA units .................................................................................................. 104 Opcodes of the BYT driver (bits 0..3) ........................................................................................ 111 RmIO interface .......................................................................................................................... 113 Function parameter ................................................................................................................... 113 Parameter pState ...................................................................................................................... 115 Parameter pParam .................................................................................................................... 117 Opcodes of the BYT driver ........................................................................................................ 118 Reserve unit (BYT_RESERVE) ................................................................................................ 118 Release unit (BYT_RELEASE) ................................................................................................. 120 Read (BYT_READ) ................................................................................................................... 121 Write (BYT_WRITE) .................................................................................................................. 123 Unconditional writing (BYT_XWRT) .......................................................................................... 125 Read character in transparent mode (BYT_ONE_XREAD) ...................................................... 125 Write and read in transparent mode (BYT_WRT_XREAD) ....................................................... 125 Write and read (BYT_WRT_READ) .......................................................................................... 126 RMOS3 V3.50 Reference Manual Part II 4 Programming Manual, 07/2012, A5E03692298-01 Table of contents 5.2.3.9 5.2.3.10 5.2.3.11 5.2.3.12 5.2.3.13 5.2.3.14 5.2.3.15 5.2.3.16 5.2.4 5.2.4.1 5.2.4.2 5.2.4.3 5.2.4.4 5.2.4.5 5.2.4.6 5.2.4.7 5.2.4.8 Skip line (BYT_SKIP_LINE) .......................................................................................................127 Clear screen (BYT_FORM_FEED) ............................................................................................127 Read character to buffer in transparent mode (BYT_HSFS_XREAD) .......................................127 Write character (BYT_HSFS_WRT) ...........................................................................................128 Read interim buffer in transparent mode (BYT_POLL_XBUF) ..................................................128 Check input buffer for abort characters (BYT_CHECK_ABO) ...................................................129 Redefine and initialize the unit (BYT_CREATE_NEW) ..............................................................130 Multifunction (only for EGA units) ..............................................................................................131 Configuration ..............................................................................................................................141 Driver Control Data table (RmDCDStruct in RMTYPES.H) .......................................................142 Unit Control Data table (RmUCDStruct in RMTYPES.H) ..........................................................142 Driver-specific parameters in the UCD block .............................................................................143 Interrupt routines of the BYT driver ............................................................................................153 Configuring the control characters in Rinitbyt.c .........................................................................154 EGA-specific configuration ........................................................................................................155 Ribtega.c ....................................................................................................................................156 Stack requirements of the BYT driver ........................................................................................159 5.3 5.3.1 5.3.1.1 5.3.1.2 5.3.1.3 5.3.1.4 5.3.2 5.3.2.1 5.3.2.2 5.3.2.3 5.3.3 5.3.3.1 5.3.3.2 5.3.3.3 5.3.3.4 5.3.3.5 5.3.3.6 5.3.3.7 5.3.3.8 5.3.3.9 5.3.3.10 5.3.3.11 5.3.3.12 5.3.3.13 5.3.3.14 5.3.3.15 5.3.4 5.3.4.1 5.3.4.2 5.3.4.3 5.3.4.4 5.3.4.5 CRT drivers ................................................................................................................................160 Properties ...................................................................................................................................160 Sequence of functions ...............................................................................................................160 Timeout handling........................................................................................................................160 Control characters ......................................................................................................................161 Opcodes of the CRT driver (bits 0 to 3) .....................................................................................162 RmIO interface ...........................................................................................................................162 Function parameter ....................................................................................................................163 Parameter pState .......................................................................................................................164 Parameter pParam .....................................................................................................................165 Opcodes of the CRT driver ........................................................................................................165 Reserve unit (CRT_RESERVE) .................................................................................................165 Release unit (CRT_RELEASE) ..................................................................................................166 Read (CRT_READ) ....................................................................................................................166 Write (CRT_WRITE) ..................................................................................................................167 Write (CRT_WRITE) ..................................................................................................................167 Read character in transparent mode (CRT_ONE_XREAD) ......................................................168 Write and read in transparent mode (CRT_WRT_XREAD) .......................................................168 Write and read (CRT_WRT_READ) ...........................................................................................169 Line feed/skip line (CRT_SKIP_LINE) .......................................................................................169 Form feed/clear screen (CRT_FORM_FEED) ...........................................................................169 Read character in transparent mode (CRT_HSFS_XREAD) .....................................................170 Write character (CRT_HSFS_WRITE) .......................................................................................170 Redefine unit (CRT_CREATE_NEW) ........................................................................................170 Keyboard control characters for I/O devices ..............................................................................171 ASCII codes used by the CRT DRIVER ....................................................................................171 Configuration ..............................................................................................................................172 Driver control data table (DCD)..................................................................................................172 Unit Control Data table (UCD) ...................................................................................................172 Driver-specific parameters in the UCD block .............................................................................173 Interrupt routines of the CRT2 driver .........................................................................................177 Stack requirements of the CRT2 driver .....................................................................................177 5.4 5.4.1 RAM disk driver ..........................................................................................................................178 Properties ...................................................................................................................................178 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 5 Table of contents 5.4.1.1 5.4.1.2 5.4.2 5.4.2.1 5.4.2.2 5.4.2.3 5.4.3 5.4.3.1 5.4.3.2 5.4.3.3 5.4.3.4 5.4.3.5 5.4.3.6 5.4.3.7 5.4.3.8 5.4.4 5.4.4.1 5.4.4.2 Sequence of the RmIO system call ........................................................................................... 179 Opcodes of the RAM DISK driver ............................................................................................. 179 RmIO interface .......................................................................................................................... 180 Function parameter ................................................................................................................... 180 Parameter pState ...................................................................................................................... 181 Parameter pParam .................................................................................................................... 182 Opcodes .................................................................................................................................... 183 Reserve RAM DISK (00H) ........................................................................................................ 183 Release RAM DISK (01H)......................................................................................................... 183 Read logical block (02H) ........................................................................................................... 184 Write logical block (03H) ........................................................................................................... 184 Dummy operation (04H) ............................................................................................................ 184 Read logical blocks (05H) ......................................................................................................... 185 Write logical blocks (06H) ......................................................................................................... 185 I/O control operation (0EH) ....................................................................................................... 186 Configuration ............................................................................................................................. 187 Driver control data (DCD) table ................................................................................................. 187 Unit Control Data table .............................................................................................................. 188 5.5 5.5.1 5.5.1.1 5.5.1.2 5.5.1.3 5.5.2 5.5.2.1 5.5.2.2 5.5.2.3 5.5.3 5.5.3.1 5.5.3.2 5.5.3.3 5.5.3.4 5.5.3.5 5.5.3.6 5.5.3.7 5.5.3.8 DMA driver ................................................................................................................................ 190 Properties .................................................................................................................................. 190 Functionality of the DMA driver ................................................................................................. 190 Note for use as subprogram...................................................................................................... 190 Special features of the DMA controller ..................................................................................... 190 RmIO interface .......................................................................................................................... 191 Function parameter ................................................................................................................... 191 Parameter pState ...................................................................................................................... 192 Parameter pParam .................................................................................................................... 193 Opcodes .................................................................................................................................... 193 Reserve unit (DMA_RESERVE) ............................................................................................... 193 Release unit (DMA_RELEASE) ................................................................................................ 194 Read from memory (DMA_READ) ............................................................................................ 194 Write to memory (DMA_WRITE) ............................................................................................... 194 Transmission abortion (DMA_ABORT) ..................................................................................... 195 Redefine unit (DMA_CREATE) ................................................................................................. 195 Subprogram calls of the DMA driver ......................................................................................... 196 Program call (X_DM2_DRIVER) ............................................................................................... 199 5.6 5.6.1 5.6.1.1 5.6.1.2 5.6.2 5.6.2.1 5.6.2.2 5.6.2.3 5.6.3 5.6.3.1 5.6.3.2 5.6.3.3 5.6.3.4 5.6.3.5 5.6.3.6 FD0 driver.................................................................................................................................. 200 Properties .................................................................................................................................. 200 Sequence of functions ............................................................................................................... 201 Opcodes of the FD0 driver ........................................................................................................ 201 RmIO interface .......................................................................................................................... 202 Function parameter ................................................................................................................... 202 Parameter pState ...................................................................................................................... 203 Parameter pParam .................................................................................................................... 205 Opcodes .................................................................................................................................... 206 Reserve unit (FD2_RESERVE) ................................................................................................. 206 Release unit (FD2_RELEASE) ................................................................................................. 206 Read logical block (FD2_READ_1) ........................................................................................... 207 Write logical block (FD2_WRITE_1) .......................................................................................... 207 Format floppy disk (FD2_FORMAT) ......................................................................................... 207 Read logical blocks (FD2_READ) ............................................................................................. 207 RMOS3 V3.50 Reference Manual Part II 6 Programming Manual, 07/2012, A5E03692298-01 Table of contents 5.6.3.7 5.6.3.8 5.6.3.9 5.6.3.10 5.6.3.11 5.6.3.12 5.6.4 5.6.4.1 5.6.4.2 5.6.4.3 5.6.4.4 Write logical blocks (FD2_WRITE) .............................................................................................208 Position to track (FD2_SEEK) ....................................................................................................208 Position to track 0 (FD2_RECA) ................................................................................................208 Get drive status (FD2_UNIT_RDY) ............................................................................................208 Remove drive parameters (delete) (FD2_DELETE) ..................................................................209 Define drive parameters (create) (FD2_CREATE) ....................................................................209 Configuration ..............................................................................................................................210 Driver control data (DCD) table..................................................................................................210 Unit Control Data (UCD) table ...................................................................................................210 Interrupt routines of the FD0 driver ............................................................................................216 Stack requirements of the FD0 driver ........................................................................................216 5.7 5.7.1 5.7.1.1 5.7.2 5.7.2.1 5.7.2.2 5.7.2.3 5.7.3 5.7.3.1 5.7.3.2 5.7.3.3 5.7.3.4 5.7.3.5 5.7.3.6 5.7.3.7 5.7.3.8 5.7.3.9 5.7.3.10 5.7.4 5.7.4.1 5.7.4.2 5.7.4.3 5.7.4.4 5.7.4.5 HD0 driver ..................................................................................................................................217 Properties ...................................................................................................................................217 Area of application and opcode .................................................................................................218 RmIO interface ...........................................................................................................................218 Function parameter ....................................................................................................................219 Parameter pState .......................................................................................................................220 Parameter pParam .....................................................................................................................222 Opcodes .....................................................................................................................................223 Reserve unit (00H) .....................................................................................................................223 Release unit (01H) .....................................................................................................................223 Read logical block (02H) ............................................................................................................223 Write logical block (03H) ............................................................................................................223 Format hard disk (04H) ..............................................................................................................224 Read logical blocks (05H) ..........................................................................................................224 Write logical blocks (06H) ..........................................................................................................224 Read drive parameters (0AH) ....................................................................................................225 Remove drive parameters (delete or dismount) (0BH) ..............................................................225 Define drive parameters (create or mount) (0CH) .....................................................................225 Configuration ..............................................................................................................................226 Driver control data (DCD) table..................................................................................................226 Unit Control Data (UCD) table ...................................................................................................226 Driver-specific parameters in the UCD block .............................................................................227 Interrupt routines of the HD0 driver............................................................................................233 Stack requirements of the HD0 driver ........................................................................................233 5.8 5.8.1 5.8.1.1 5.8.1.2 5.8.1.3 5.8.1.4 5.8.1.5 5.8.1.6 5.8.1.7 5.8.2 5.8.2.1 5.8.2.2 5.8.2.3 5.8.3 5.8.3.1 5.8.3.2 COM driver .................................................................................................................................234 Properties ...................................................................................................................................234 Sequence of functions ...............................................................................................................234 Timeout handling........................................................................................................................235 Transfer protocol ........................................................................................................................235 Signal sequences .......................................................................................................................236 Example of signal sequences ....................................................................................................238 Control characters ......................................................................................................................241 Opcodes of the COM driver .......................................................................................................241 RmIO interface ...........................................................................................................................242 Function parameter ....................................................................................................................242 Parameter pState .......................................................................................................................243 Parameter pParam .....................................................................................................................244 Opcodes .....................................................................................................................................245 Reserve unit (C64_RESERVE) ..................................................................................................245 Release unit (C64_RELEASE)...................................................................................................246 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 7 Table of contents A 5.8.3.3 5.8.3.4 5.8.3.5 5.8.4 5.8.4.1 5.8.4.2 5.8.4.3 5.8.4.4 5.8.4.5 Read (C64_READ) .................................................................................................................... 246 Write (C64_WRITE) .................................................................................................................. 247 Redefine unit (C64_CREATE_NEW) ........................................................................................ 247 Configuration ............................................................................................................................. 248 Driver Control Data table (RmDCDStruct in RMTYPES.H) ...................................................... 248 Unit Control Data table (RmUCDStruct in RMTYPES.H) ......................................................... 249 Driver-specific parameters in the UCD block ............................................................................ 249 Interrupt routines of the COM driver ......................................................................................... 254 Stack requirements of the COM driver ...................................................................................... 255 5.9 5.9.1 5.9.1.1 5.9.2 5.9.2.1 5.9.2.2 5.9.2.3 5.9.3 5.9.3.1 5.9.3.2 5.9.3.3 5.9.3.4 5.9.3.5 5.9.3.6 5.9.3.7 5.9.3.8 5.9.4 5.9.4.1 5.9.4.2 SRAM driver .............................................................................................................................. 256 Areas of application ................................................................................................................... 256 Organization of tasks/functions ................................................................................................. 256 RmIO interface .......................................................................................................................... 257 Function parameter ................................................................................................................... 258 Parameter pState ...................................................................................................................... 259 Parameter pParam .................................................................................................................... 260 Opcodes .................................................................................................................................... 260 Reserve unit (RD40_RESERVE) .............................................................................................. 260 Release unit (RD40_FREE) ...................................................................................................... 260 Read logical block (RD40_READ_ONE) ................................................................................... 261 Write logical block (RD40_WRITE_ONE) ................................................................................. 261 Format (RD40_FORMAT) ......................................................................................................... 261 Read logical blocks (RD40_READ_MORE) .............................................................................. 262 Write logical blocks (RD40_WRITE_MORE) ............................................................................. 262 I/O control operation (RD40_IOCTRL) ...................................................................................... 262 Configuration ............................................................................................................................. 264 Driver control data (DCD) table ................................................................................................. 264 Unit Control Data (UCD) table................................................................................................... 265 Abbreviations/glossary .........................................................................................................................267 Index ...................................................................................................................................................275 RMOS3 V3.50 Reference Manual Part II 8 Programming Manual, 07/2012, A5E03692298-01 Table of contents 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 9 Table of contents 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 10 Programming Manual, 07/2012, A5E03692298-01 About this manual... 1.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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 11 About this manual... 1.2 Notations 1.2 Notations We use the following notation to enhance legibility of the RMOS3 documentation: Commands Commands control program sequences in dialog or batch mode. The Courier font is used in the text to highlight the commands. A command consists of at least one element. Elements are constants or variables. They are comprised of letters, numbers and special characters (e.g. #*?). The Courier font is also used to present program listings. They are printed in compliance with the characters and do not follow the notation for commands. The programming language C, for example, distinguishes between uppercase and lowercase notation. Table 1- 1 Commands Representation Property Comment UPPERCASE Constant Elements in uppercase notation represent constants. Entries are made in accordance with the character notation with support of uppercase and lowercase letters. 1847 Constant Numbers are always constants. x Variable Elements in lowercase notation represent variables that can be replaced by current elements. ()\:;> Special characters Special characters and whitespaces serve as delimiters between elements and always need to be entered. The use of elements is described by meta characters. Meta characters are not entered. Representation Property Comment <> Delimiters Variables are enclosed in angled brackets [] Optional Elements in angled brackets are optional. 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. |a|b|c| ... Abbreviations A number of abbreviations and short names apply to the entire RMOS3 documentation: Table 1- 2 Abbreviations Abbreviation Meaning Text passage cfg configurable System calls uintmax maximum unsigned integer (FFFF FFFFH) System calls dp data pointer (sel:off) 48-bit pointer System calls RMOS3 V3.50 Reference Manual Part II 12 Programming Manual, 07/2012, A5E03692298-01 About this manual... 1.2 Notations Data types The following data types may be used for the C compilers approved for RMOS3: Table 1- 3 General data types Data type Data length char 8 bit short 16 bit int 32 bit long long 32 bit long 1 64 bit void _FAR * 2 48 bit void _NEAR * 32 bit 2 enum 32 bit float 32 bit double 64 bit 1 Only available for GNU programs. 2 Pointers in flat programs always have a length of 32 bit. No distinction is made between NEAR and FAR. Table 1- 4 Data types of the RMOS3 API Name Data type Data length uchar unsigned char 8 bit ushort unsigned short 16 bit uint unsigned int 32 bit ulong unsigned long 32 bit rmfarproc 1 Pointer to function type void _FAR f(void) 48 bit rmnearproc 1 Pointer to function type void _NEAR f(void) 32 bit rmproc 1 Pointer to function type void _NEAR f(void) 32 bit 1 Pointers in flat programs always have a length of 32 bit. No distinction is made between NEAR and FAR. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 13 About this manual... 1.2 Notations RMOS3 V3.50 Reference Manual Part II 14 Programming Manual, 07/2012, A5E03692298-01 2 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: 2.1 RMOS3 kernel functions libhlig.a CLI functions libclig.a C library functions libcrig.a 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 15 Function groups 2.1 RMOS3 functions 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. RMOS3 V3.50 Reference Manual Part II 16 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.1 RMOS3 functions 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 17 Function groups 2.1 RMOS3 functions 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 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 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 Descriptors Task control RMOS3 V3.50 Reference Manual Part II 18 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.1 RMOS3 functions 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 RmSetTaskPriority Terminate interval that was initiated with RmSuspendTask or RmPauseTask Change task priority RmStartTask Task start request for tasks in DORMANT state. RmSuspendTask Set task to BLOCKED state RmCatalog Enter resource in resource catalog RmGetEntry Find catalog entry RmGetName Search catalog for entry RmList List catalog entries RmUncatalog Remove resource from catalog 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 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 Resources Messages Mails RmSendMailDelayed RmSetMailboxSize Transfer mail to mailbox with time-delay Set mailbox limits RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 19 Function groups 2.1 RMOS3 functions 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 RmCreateBinSemaphore Define dynamic semaphore RmDeleteBinSemaphore Delete dynamic semaphore RmReleaseBinSemaphore Reset semaphore RmGetBinSemaphore Test and set semaphore RmInitSpinLock Initialize SpinLock RmGetSpinLock Request SpinLock RmGetSpinLockIRQ Request SpinLock and disable interrupts RmReleaseSpinLock Release SpinLock RmReleaseSpinLockIRQ Release SpinLock and enable interrupts Semaphores SpinLocks 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 RMOS3 V3.50 Reference Manual Part II 20 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.1 RMOS3 functions 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 RmInitHPET Initialize function for reading HPET timer 0 RmGetTimeHPET0 Read current counter of HPET timer 0 RmGetPeriodHPET0 Query period of HPET timer 0 RmCreateDriver Register static or reloadable driver at the operating system RmCreateUnit Register unit at the operating system RmIO Request I/O operation RmResumeDriver Define new device driver RmSuspendDriver Suspend device driver (set to BLOCKED state) RmDecode Decode RMOS3 error number RmGetSysB Read System Control Block RmGetIntHandler Read interrupt handler RmReserveInterrupt 1 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 1 Create driver interrupt handler RmSetIntDefHandler Install default interrupt handler HPET functions Drivers System Interrupt handlers 1 Effective only at system startup RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 21 Function groups 2.1 RMOS3 functions 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 RmHookException Hook callback function that is called on exception RmSetProfilerPoint Set orientation points in the profiler for "Task Activity" measurement Miscellaneous RMOS3 V3.50 Reference Manual Part II 22 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.1 RMOS3 functions 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 Register 3964 driver in RMOS3 RcInit3964r8250 Register 8250 block at the 3964 driver RcInit3964r8530 Register 8530 block at the 3964 driver RcInit3964rCOM1 Register COM1 interface at the 3964 driver RcInit3964rCOM2 Register COM2 interface at the 3964 driver RcInit8254 Initialize 8254 timer RcInit8259A Initialize 8259A interrupt controller RcInitByt Register BYT driver in RMOS3 RcInitByt8250 Register 8250 block at the BYT driver RcInitByt8251 Register 8251 block at the BYT driver RcInitByt8255 Register PC line printer at the BYT driver RcInitByt8530 Register 8530 block at the BYT driver RcInitBytCOM1 Register COM1 interface at the BYT driver RcInitBytCOM2 Register COM2 interface at the BYT driver RcInitBytEga Register EGA display adapter at the BYT driver RcInitBytLPT1 Register LPT1 at the BYT driver RcInitBytLPT2 Register LPT2 at the BYT driver RcInitCLIDispatcher Create dispatcher task for debugger and CLI RcInitCrt Register CRT driver in RMOS3 RcInitCrt8250 Register 8250 block at the CRT driver RcInitCrtCOM1 Register COM1 interface at the CRT driver RcInitCrtCOM2 Register COM2 interface at the CRT driver RcInitDEBDispatcher Create dispatcher task without CLI RcInitDebugger Create debugger RcInitEmul Initialize co-processor emulator RcInitErrorLogger Create error logger task RcInitFd0 Register PC floppy driver in RMOS3 RcInitHd0 Register PC HD driver in RMOS3 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 23 Function groups 2.1 RMOS3 functions 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 Register RAM disk driver in RMOS3 RcInitRamdisk32 Register RAM disk driver in RMOS3 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) RMOS3 V3.50 Reference Manual Part II 24 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.1 RMOS3 functions 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 stl_load Load task stl_free De-allocate task x_hd_init Integration of one or several HD partitions into the HSFS Task operations HDD functions System functions for BUSY task x_bu_init Initialize BUSY task x_bu_get Query average system idle time in percent RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 25 Function groups 2.2 CLI functions 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. RMOS3 V3.50 Reference Manual Part II 26 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.2 CLI functions 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_cmdexec Execute CLI command x_cli_extended_session or x_cli_extended_start. 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 27 Function groups 2.3 C library functions 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. RMOS3 V3.50 Reference Manual Part II 28 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.3 C library functions 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 29 Function groups 2.3 C library functions 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. RMOS3 V3.50 Reference Manual Part II 30 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.3 C library functions 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 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 31 Function groups 2.3 C library functions 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 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 RMOS3 V3.50 Reference Manual Part II 32 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.3 C library functions 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 33 Function groups 2.3 C library functions 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 RMOS3 V3.50 Reference Manual Part II 34 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.3 C library functions 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 tanh Tangent 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) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 35 Function groups 2.3 C library functions 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 RMOS3 V3.50 Reference Manual Part II 36 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.4 Driver functions 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 calls 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 37 Function groups 2.4 Driver functions 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 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 Assembler and C 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) RMOS3 V3.50 Reference Manual Part II 38 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.4 Driver functions 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. 2.4.4 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 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 39 Function groups 2.4 Driver functions 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 DD WRITE_BLK DD CLEAR_UNIT ;code 2: read a block ;code 3: write a block ;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. RMOS3 V3.50 Reference Manual Part II 40 Programming Manual, 07/2012, A5E03692298-01 Function groups 2.4 Driver functions 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 41 Function groups 2.4 Driver functions RMOS3 V3.50 Reference Manual Part II 42 Programming Manual, 07/2012, A5E03692298-01 3 Data structures 3.1 Syntax RmAbsTimeStruct #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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 43 Data structures 3.2 RmAsciiTimeStruct 3.2 Syntax RmAsciiTimeStruct #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 RMOS3 V3.50 Reference Manual Part II 44 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.3 RmDCDStruct 3.3 Syntax RmDCDStruct #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 UCD address units RmUCDStruct uchar Reserved shr uchar Device number of a shared device (0FFH=no sharing) init rmproc Address of the driver init routine svc rmproc flags uchar Address of the RmIO entry point 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) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 45 Data structures 3.4 RmEntryStruct 3.4 Syntax RmEntryStruct #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 RMOS3 V3.50 Reference Manual Part II 46 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.5 RmIntrhandMailStruct 3.5 Syntax RmIntrhandMailStruct #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 0 Hardware interrupt 1 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 47 Data structures 3.6 RmIOStatusStruct 3.6 Syntax RmIOStatusStruct #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 RMOS3 V3.50 Reference Manual Part II 48 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.7 RmIRBStruct 3.7 Syntax RmIRBStruct #include <rmtypes.h> typedef struct _RmIRBStruct { struct _RmIRBStruct ushort pri; struct _RmTCBStruct struct _RmUCBStruct struct _RmTMBStruct 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 _NEAR * tcb; _NEAR * ucb; _NEAR * tmb; The RmIRBStruct structure defines a structure for I/O requests (RmIO). Field Type Meaning link Pointer to RmIRBStruct Forward link or 0 ushort Priority Pointer to RmTCBStruct TCB address of the requesting task Pointer to RmTMBStruct TMB address of current request funct pri tcb ucb Pointer to RmUCBStruct UCB address of the requested device uchar Start of SDB image 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 tmb rio See also _NEAR * link; RmIO RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 49 Data structures 3.8 RmMailboxStruct 3.8 Syntax RmMailboxStruct #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 RMOS3 V3.50 Reference Manual Part II 50 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.9 RmMailIDStruct 3.9 Syntax RmMailIDStruct #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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 51 Data structures 3.10 RmMemPoolInfoStruct 3.10 Syntax RmMemPoolInfoStruct #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 RMOS3 V3.50 Reference Manual Part II 52 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.11 RmSpinLockStruct 3.11 Syntax RmSpinLockStruct #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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 53 Data structures 3.12 RmSysB 3.12 Syntax RmSysB #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; RMOS3 V3.50 Reference Manual Part II 54 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.12 RmSysB #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: systemtype ushort Bit pattern Single information 0x0F00 CPU type 0x00F0 CPU model (Pentium) 0x000F CPU stepping (Pentium) 0x8000 FPU available RMOS type Value Meaning 2 RMOS2 3 RMOS3 4 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 55 Data structures 3.12 RmSysB See also Field Type Meaning bootdrive uchar RMOS3 boot drive Value Meaning 0 Floppy drive 0 1 Hard disk 0 2 Memory card 3 LAN 4 EPROM 5 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) res8f ushort Function putchar for nucleus outputs Reserved RmGetSysB RMOS3 V3.50 Reference Manual Part II 56 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.13 RmTaskInfoStruct 3.13 Syntax RmTaskInfoStruct #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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 57 Data structures 3.13 RmTaskInfoStruct Field Type Meaning RM_STA_PAUSE RM_STA_CNTRL Waiting for expiration of time interval (RmPauseTask) 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) Pointer to TCD address ushort Fill word for FLAT model tcd_ptr tcd_ptr_res RmTCDStruct RMOS3 V3.50 Reference Manual Part II 58 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.14 RmTCDStruct 3.14 Syntax RmTCDStruct #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: RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 59 Data structures 3.14 RmTCDStruct Field Type Meaning eax uint Value transferred on the stack at task start. ebx uint Value transferred in the EBX register at task start. ds ushort Returns the length of the data segment in bytes. es 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 * load_res ushort Address of the load descriptor string for reloadable task, otherwise (char *) 0. 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: Fill word for FLAT model Symbolic name *) Time unit RM_TCD_MSEC_1 00 1 ms RM_TCD_MSEC_10 04 10 ms RM_TCD_MSEC_100 08 100 ms RM_TCD_SEC 12 1s RM_TCD_SEC_10 24 10 s RM_TCD_MIN 16 1 min RM_TCD_MIN_10 28 10 min HOUR 20 1h *) value (decimal) to enter for ?? ovpri uchar The task priority is incremented by this value if runtimedependent 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 RMOS3 V3.50 Reference Manual Part II 60 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.14 RmTCDStruct 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 RM_TFL_DS Specifies that RMOS3 automatically allocates system HEAP memory space to the task stack. 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 61 Data structures 3.15 RmTimeStruct 3.15 Syntax RmTimeStruct #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 RMOS3 V3.50 Reference Manual Part II 62 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.16 RmTMBStruct 3.16 Syntax RmTMBStruct #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; RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 63 Data structures 3.16 RmTMBStruct /* *** 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 Pointer to Forward link or 0 uint Least significant DWORD of the absolute time htime uint Most significant DWORD of the absolute time type uchar TMB type: link ltime RmTMBStruct Value Meaning 1 Driver or tod timeout 2 Task pause timeout 3 Event flag 4 Task restart timer 5 Override priority timer 6 Reserved 7 Reserved 8 SVC timeout 9 Message delay TMB type 1 Field Type Meaning res uchar Reserved ucb Pointer to UCB address sadr void* Address of the timeout routine ushort Fill word for FLAT model sadr_seg RmUCBStruct RMOS3 V3.50 Reference Manual Part II 64 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.16 RmTMBStruct TMB type 2 Field Type Meaning res uchar Reserved tcb Pointer to TCB address Field Type Meaning res uchar Reserved efgrp uchar Event flag group tcb Pointer to TCB address efmsk uint Flag mask Field Type Meaning res uchar Reserved tcb Pointer to TCB address Field Type Meaning res uchar Reserved tcb Pointer to TCB address ovpri RmTCBStruct TMB type 3 RmTCBStruct TMB type 4 RmTCBStruct TMB type 5 RmTCBStruct uchar Priority increment bpri uchar Priority limit ovtime uchar Priority time interval in ms Field Type Meaning res uchar Reserved tcb Pointer to TCB address swb uint Address of the semaphore wait block uint Semaphore address TMB type 6 sem RmTCBStruct RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 65 Data structures 3.16 RmTMBStruct TMB type 7 Field Type Meaning res uchar Reserved irb Pointer to IRB address Field Type Meaning res uchar Reserved tjt uint Timeout jump table svc ushort Bit-coded SVC qh uint Specific queue header wb uint Specific wait block Field Type Meaning res uchar Reserved alarm uint Alarm routine called on expiration tib uint Associated TIB RmIRBStruct TMB type 8 TMB type 9 See also RmTCDStruct (Page 59) RMOS3 V3.50 Reference Manual Part II 66 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.17 RmUCDHeadStruct 3.17 Syntax RmUCDHeadStruct #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) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 67 Data structures 3.18 RmUCDStruct 3.18 Syntax RmUCDStruct #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) RMOS3 V3.50 Reference Manual Part II 68 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.19 loader_result 3.19 Syntax loader_result #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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 69 Data structures 3.19 loader_result 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 reserved_ word3 ushort Field that contains all segment selectors of the loaded task. The length of the field is stored in num_more_slots. Reserved. reserved_ pointer1 void* Reserved. See also stl_load RMOS3 V3.50 Reference Manual Part II 70 Programming Manual, 07/2012, A5E03692298-01 Data structures 3.20 stdstruct 3.20 Syntax stdstruct #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 -3 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. 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 71 Data structures 3.20 stdstruct 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 72 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.1 4 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 73 Error codes and messages 4.1 Nucleus 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: 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. AT ADDRESS RMOS3 V3.50 Reference Manual Part II 74 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.1 Nucleus 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 75 Error codes and messages 4.2 Error codes of the RMOS3 API calls 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). RMOS3 V3.50 Reference Manual Part II 76 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.2 Error codes of the RMOS3 API calls 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 77 Error codes and messages 4.2 Error codes of the RMOS3 API calls 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. RMOS3 V3.50 Reference Manual Part II 78 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.2 Error codes of the RMOS3 API calls 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 79 Error codes and messages 4.3 SVC exception handler 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: <CoreID> ID of the core at which the error has occurred <name> Decoded SVC name, e.g. RmGetFlag <status text> One of the following text strings is inserted, depending on the system state at the call of the SVC exception handler. 1. from task: <name> id: 0xXX 2. during system startup 3. in monitor mode 4. in s-state 5. 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) RMOS3 V3.50 Reference Manual Part II 80 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.4 CLI 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 0 E_CLI_NOT_RESIDENT No resident task 0x8201 E_CLI_FILE_FORMAT Invalid file format 0x8202 E_CLI_DYNAMIC_MEM Out of dynamic memory 0x8203 E_CLI_INTERNAL_ERROR Internal error 0x8204 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 0x8205 0x8206 0x8207 0x8208 0x8209 0x820A 0x820B 0x820C 0x820D 0x820E 0x820F 0x8210 0x8211 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 81 Error codes and messages 4.4 CLI E_CLI_NO_COMMAND Command not available 0x8212 E_CLI_EOF End of file 0x8213 E_CLI_EXIT_STATUS Exit status (as return value of the EXIT command) 0x8214 E_CLI_CATALOG_FULL RMOS3 catalog is full 0x8215 E_CLI_CREATESEMA_ERROR Error when creating a semaphore 0x8216 E_CLI_REDIR_STDIN_FAIL Error when redirecting stdin 0x8217 E_CLI_REDIR_STDOUT_FAIL Error when redirecting stdout 0x8218 E_CLI_REDIR_STDERR_FAIL Error when redirecting stderr 0x8219 E_CLI_UNKNOWN_SWITCH Unknown switch 0x821A E_CLI_TOO_MANY_PARAMS Too many parameters 0x821B E_CLI_INVALID_FILENAME Invalid file name 0x821C E_CLI_INVALID_LT_INDEX Invalid task index 0x821D E_CLI_INVALID_JOB_INDEX Invalid CLI job number 0x821E E_CLI_TOO_FEW_PARAMS Insufficient number of parameters 0x821F E_CLI_FILE_READ_ERROR File read error 0x8220 E_CLI_FILE_WRITE_ERROR File write error 0x8221 E_CLI_COPY_TO_SELF Attempt to copy a file to itself 0x8222 E_CLI_UNEXPECTED_EOF Unexpected EOF reached 0x8223 E_CLI_PERMANENT_TASK Permanent CLI task 0x8224 E_CLI_NO_PROMPT Missing prompt definition 0x8225 E_CLI_JOB_ABORTED Job was aborted 0x8226 E_CLI_NOT_A_DEVICE Not a device name 0x8227 RMOS3 V3.50 Reference Manual Part II 82 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.4 CLI E_CLI_MKDIR_FAIL Creation of directory failed 0x8228 E_CLI_BATCH_FILE File is a batch file 0x8229 E_CLI_NOT_MOUNTED Volume not mounted 0x822A E_CLI_INVALID_WILDCARD Invalid use of wildcards 0x822B E_CLI_NOT_A_DIRECTORY Not a directory 0x822C E_CLI_DIR_OPEN_FAIL Failed to open directory 0x822D E_CLI_FILE_OPEN_FAIL Failed to open file 0x822E E_CLI_FILE_CLOSE_FAIL Failed to close file 0x822F E_CLI_SVC_ERROR SVC error 0x8230 E_CLI_DEV_READ_ERROR Error when reading from device 0x8231 E_CLI_DEV_WRITE_ERROR Error when writing to device 0x8232 E_CLI_IS_A_DIRECTORY File is a directory 0x8233 E_CLI_INLINE Inline CLI command 0x8234 E_CLI_COMPLETED CLI job is completed 0x8235 E_CLI_UNINITIALISED CLI job was not initialized 0x8236 E_CLI_OUT_OF_RANGE Index out of range 0x8237 E_CLI_NO_SPACE_FOR_NPX Setup of NPX context failed when creating the task 0x8238 E_CLI_NO_PARENT_JOB No parent job 0x8239 E_CLI_INVALID_VOL_NAME Invalid volume name 0x823A E_CLI_MOUNTED Volume is mounted 0x823B E_CLI_INVALID_DATE_TIME Invalid date or time format 0x823C E_CLI_READ_ONLY File is read only 0x823D RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 83 Error codes and messages 4.5 CRUN 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> <time> <error message> <taskname> <taskid> Date at which the error occurred Time at which the error occurred Actual error message String by which the task that 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 . RMOS3 V3.50 Reference Manual Part II 84 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.5 CRUN 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 85 Error codes and messages 4.6 HSFS 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. RMOS3 V3.50 Reference Manual Part II 86 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.7 Debugger 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 87 Error codes and messages 4.7 Debugger 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. RMOS3 V3.50 Reference Manual Part II 88 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.7 Debugger 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 89 Error codes and messages 4.8 Resource reporter 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. RMOS3 V3.50 Reference Manual Part II 90 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.9 Task loader stl_load, stl_free 4.9 Task loader stl_load, stl_free Error number Error message Meaning 0H 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: PE: 1st 1st 1st NEW word = 0206H 16-bit word = "M2" 32-bit word of 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 91 Error codes and messages 4.9 Task loader stl_load, stl_free 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 RMOS3 V3.50 Reference Manual Part II 92 Programming Manual, 07/2012, A5E03692298-01 Error codes and messages 4.10 LOADRM task loader 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 93 Error codes and messages 4.10 LOADRM task loader RMOS3 V3.50 Reference Manual Part II 94 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.1 5 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 95 Functions and configuration of the basic I/O system 5.2 BYT driver 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. Byteoriented 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. RMOS3 V3.50 Reference Manual Part II 96 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 onscreen 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 identified 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 97 Functions and configuration of the basic I/O system 5.2 BYT driver 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 R Call E S E R V E 1st Call R E L E A S E R E A D W R I T E X W R T O N E _ X R E A D W R T _ X R E A D W R T _ R E A D S K I P _ L I N E F O R M _ F E E D H S F S _ X R E A D H S F S _ W R I T E P O L L _ X B U F F C H E C K _ A B O C R E A T E _ N Multifunction E W 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 RESERVE 00 - - - - - - - - - - - - - - - - RELEASE 01 - - - - - - - - - - - - - - - - READ 02 - - - - + - - - - - - - - + - - WRITE 03 - - - - - + 2 - - - + - + + - - XWRT 04 - + - - - + 2 2 - - + - + + - - ONE_XREAD 05 - - - + + - 4 4 + + - + - + - - WRT_XREAD 06 - - - 1 1 3 - - 1 1 3 1 - + - - WRT_READ 07 - - - - 1 3 - - - - 3 - - + - - SKIP_LINE 08 - - - - - + 2 - - - + - + + - - FORM_FEED 09 - - - - - + 2 - - - + - + + - - HSFS_XREAD 10 - - - + + - 4 4 + + - + - + - - HSFS_WRITE 11 - - - - - + 2 - - - + - + + - - POLL_XBUFF 12 - - - + + - - - + + - + - - - - CHECK_ABO 13 - - + + + + + + + + + + - - - - CREATE_NEW 14 - - - - - - - - - - - - - - - - Multifunction 15 - - - - - - - - - - - - - - - - - no simultaneous function sequence + simultaneous sequence enabled Conditional simultaneous sequence, if 1: no data output with function 1 2: no data output with function 2 3: no data input with function 1 4: no data input with function 2 RMOS3 V3.50 Reference Manual Part II 98 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 99 Functions and configuration of the basic I/O system 5.2 BYT driver 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 RMOS3 V3.50 Reference Manual Part II 100 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 101 Functions and configuration of the basic I/O system 5.2 BYT driver 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 RMOS3 V3.50 Reference Manual Part II 102 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 103 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II 104 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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.) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 105 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II 106 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 107 Functions and configuration of the basic I/O system 5.2 BYT driver 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 0 Meaning 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. RMOS3 V3.50 Reference Manual Part II 108 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 109 Functions and configuration of the basic I/O system 5.2 BYT driver 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 RMOS3 V3.50 Reference Manual Part II 110 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 111 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II 112 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 5.2.2 RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: 5.2.2.1 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. 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 7 Preemptive bit 0 Sort I/O request based on 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 Cancel bit 1 Cancel active I/O operations 0 No abortion 4 3..0 Function reserved 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). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 113 Functions and configuration of the basic I/O system 5.2 BYT driver 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 descriptors (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. RMOS3 V3.50 Reference Manual Part II 114 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 115 Functions and configuration of the basic I/O system 5.2 BYT 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. 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. RMOS3 V3.50 Reference Manual Part II 116 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver Table 5- 8 5.2.2.3 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 1 The last byte read or transferred is entered, depending on the I/O request. 2 Number of actually transferred bytes. 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 1 WORD int 6 Length of the output buffer or input request text 2 POINTER far 10 Offset/segment of the input buffer or transformation table 1 WORD int 16 Length of the input buffer, or timeout value 2 WORD int 20 Block status information 3 24 Total scope RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 117 Functions and configuration of the basic I/O system 5.2 BYT driver Parameter block of function 15 (multifunction): Type Offset Description Note BYTE char 0 Subfunction number BYTE char 1 Variable 4 WORD short 2 Variable 1 POINTER far 4 to user buffer 1 POINTER far 10 to user buffer 1 16 Total scope Note Subfunctions 0 to 18 only need a 4-byte parameter block. 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). 1 I/O data has a maximum length of 64 K. Only the least significant 2 bytes of 4 bytes are used. 2 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. 3 A description of the parameters for the corresponding parameter block is available in the description of subfunctions of the multifunction. 4 5.2.3 Opcodes of the BYT driver 5.2.3.1 Reserve unit (BYT_RESERVE) Opcode: 00H Parameter block length: 24 bytes BYT_RESERVE 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. RMOS3 V3.50 Reference Manual Part II 118 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 0 Address of the input request text WORD int 6 Length of the input request text POINTER far 10 Address of the transformation table WORD int 16 Timeout value (multiple of 256 ms) WORD int 20 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)". RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 119 Functions and configuration of the basic I/O system 5.2 BYT driver 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 must 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: Parameter block: 01H None BYT_RELEASE 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. RMOS3 V3.50 Reference Manual Part II 120 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 5.2.3.3 Read (BYT_READ) Opcode: Parameter block: 02H BYT_READ 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: 1 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 WORD int 20 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 Line feed (only in line feed mode) CR LF (0DH) (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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 121 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II 122 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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: Parameter block: 03H BYT_WRITE 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: 1 Type Offset Description Note POINTER far 0 Address of the output buffer WORD int 6 Length of the output buffer POINTER far 10 BYTE: Address of the extension table 1 WORD int 16 reserved 1 WORD int 20 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 123 Functions and configuration of the basic I/O system 5.2 BYT driver 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 X STOP CR LF IND EQU EQU EQU EQU EQU EQU ESCAPE_TABLE OUTPUT_TEXT DB 'DATE TEXT_LENGTH 01BH 0FEH 0FFH 00DH 00AH 000H ;ESCAPE CHARACTER ;FILL CHARACTER ;DELIMITER ;CARRIAGE RETURN ;LINE FEED ;INDEX FOR EXTENSION ;TABLE (ESCAPE_TABLE) DB 'YEAR: 19',X,X,' MONTH: ',X,X,' ' DAY: ',X,X,STOP ',ESC,IND,'900812',CR,LF,0 DW 43 ; OUTPUT WITH OUTPUT REQUEST AND CORRESPONDING PARAMETER ; BLOCK ALLOCATION: 'DATE YEAR: 1990 MONTH: 08 DAY: 12' RMOS3 V3.50 Reference Manual Part II 124 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 5.2.3.5 Unconditional writing (BYT_XWRT) Opcode: Parameter block: 04H BYT_XWRT 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. 1 5.2.3.6 Type Offset Description Note POINTER far 0 Address of the output buffer WORD int 6 Length of the output buffer POINTER far 10 reserved 1 WORD int 16 reserved 1 WORD int 20 Status information 1 Unrestricted interpretation Read character in transparent mode (BYT_ONE_XREAD) Opcode: Parameter block: 05H None BYT_ONE_XREAD 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: Parameter block: 06H BYT_WRT_XREAD 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 125 Functions and configuration of the basic I/O system 5.2 BYT driver 1 Type Offset Description POINTER far 0 Address of the output buffer Note WORD int 6 Length of the output buffer POINTER far 10 Address of the input buffer WORD int 16 Length of the input buffer WORD int 20 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: Parameter block: 07H BYT_WRT_READ 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. 1 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 WORD int 20 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. RMOS3 V3.50 Reference Manual Part II 126 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 5.2.3.9 Skip line (BYT_SKIP_LINE) Opcode: Parameter block: 08H BYT_SKIP_LINE 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). 1 5.2.3.10 Type Offset Description Note POINTER far 0 reserved WORD int 6 Number of carriage returns/line feeds POINTER far 10 reserved 1 WORD int 16 reserved 1 WORD int 20 Status information 1 Unrestricted interpretation Clear screen (BYT_FORM_FEED) Opcode: Parameter block: 09H None BYT_FORM_FEED 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 zero, 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: Parameter block: 0AH BYT_HSFS_XREAD 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 127 Functions and configuration of the basic I/O system 5.2 BYT driver The parameter block to initialize prior to the call has the following structure: 1 5.2.3.12 Type Offset Description Note POINTER far 0 Address of the input buffer WORD int 6 reserved 1 POINTER far 10 reserved 1 WORD int 16 reserved 1 WORD int 20 Status information 1 Unrestricted interpretation Write character (BYT_HSFS_WRT) Opcode: Parameter block: 0BH BYT_HSFS_WRT 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)). 1 5.2.3.13 Type Offset Description POINTER far 0 Address of the output buffer Note WORD int 6 reserved 1 POINTER far 10 reserved 1 WORD int 16 reserved 1 WORD int 20 Status information 1 Unrestricted interpretation Read interim buffer in transparent mode (BYT_POLL_XBUF) Opcode: Parameter block: 0CH 24 bytes BYT_POLL_XBUF 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). RMOS3 V3.50 Reference Manual Part II 128 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 1 5.2.3.14 Type Offset Description POINTER far 0 reserved Note WORD int 6 reserved POINTER far 10 Address of the input buffer WORD int 16 Length of the input buffer WORD int 20 Status information 1 Unrestricted interpretation Check input buffer for abort characters (BYT_CHECK_ABO) Opcode: Parameter block: 0DH 24 bytes BYT_CHECK_ABO 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 POINTER far 0 Address of abort feedback WORD int 6 reserved POINTER far 10 Address of the abort routine WORD int 16 reserved WORD int 20 reserved Note 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 129 Functions and configuration of the basic I/O system 5.2 BYT driver 5.2.3.15 Redefine and initialize the unit (BYT_CREATE_NEW) Opcode: Parameter block: 0EH 20 bytes BYT_CREATE_NEW 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 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 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 are to be manipulated, you (additionally) need to call the corresponding subfunction of the multifunction. RMOS3 V3.50 Reference Manual Part II 130 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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: Parameter block: 0FH 4 bytes for subfunctions 0..18 16 bytes for subfunction 19 Possible subfunction numbers: Number Function 0 Move write position to right 1 Move write position to left 2 Set write position 3 Read current write position 4 Set cursor mode 5 Scroll screen 6 Read character 7 Write character 8 Write character with attribute 9 Delete character left of write position 10 Delete character right of write position 11 Switch write page 12 Switch display page 13 Switch keyboard 14 Enable/disable output 15 Enable/disable input 16 Activate/deactivate screen scrolling 17 Activate/deactivate emulation 18 Get status 19 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 131 Functions and configuration of the basic I/O system 5.2 BYT driver 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). RMOS3 V3.50 Reference Manual Part II 132 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 133 Functions and configuration of the basic I/O system 5.2 BYT driver 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 Number of rows (0 = clear window) Input 6: Scroll screen down Window background color 0 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. RMOS3 V3.50 Reference Manual Part II 134 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 135 Functions and configuration of the basic I/O system 5.2 BYT driver 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 0 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 0 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 RMOS3 V3.50 Reference Manual Part II 136 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 137 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II 138 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 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 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 139 Functions and configuration of the basic I/O system 5.2 BYT driver 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 0 Number of columns 1 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 2 Column 3 Row Example: Coordinates of the top left corner of the window: 0:0 4 (WORD short) Bottom right corner of the window 4 Column 5 Row 6 (BYTE char) Color attribute for rows Example: Coordinates of the bottom right corner of the screen: 18H:4FH. 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 8 Top grid of the cursor in a character field 9 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. 16 Write position selector The selector values are specified in the builder session 18 8 bytes SME emulation RMOS3 V3.50 Reference Manual Part II 140 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 corner 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 141 Functions and configuration of the basic I/O system 5.2 BYT driver 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 1 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 1 5.2.4.2 FMAX Maximum function code for type II driver char 0CH RESERV 2 reserved bytes char 00H, 00H This value is occupied during system configuration. 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. 1 Parameters Offset Type Description PID 0 char reserved Note 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 10 short Driver-specific data (120/246 bytes) 256 Total 1 See Interrupt routines of the BYT driver. RMOS3 V3.50 Reference Manual Part II 142 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 10 short Unit Control Code PRTSEG 12 short USART segment PRTDAT 14 int USART data port PRTCMD 18 int USART command port PORT_2 22 int USART extra port 2 1 PORT_3 26 int USART extra port 3 1 PRTSTA 30 int USART status port 1 STMODE 34 short Status Control Mask 1 STARET 36 short Error Reset byte and retry factor for USART status check 2 TOPCHR 38 short Form feed character 2 TIMOUT 40 short Timeout value/character 2 TABBUF 42 void FAR * I/O transformation table POOLID 48 char Pool ID used to allocate interim and history buffers POOLEN 49 char Length of the interim pool UNSCHR 50 short Start character for unexpected task start RECOVR 52 char I/O delay value MODEXT 553 char Mode extension of the driver ICOUNT 54 short Number of init outputs 3 MOBYTE 56 short 1. Initialization output 2 ..... ... MOBYTE 254 short nth init output 1 2 1 1 These parameters are insignificant in an EGA configuration and must be set to 0. 2 These parameters require special declarations for an EGA configuration (see below). 3 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 143 Functions and configuration of the basic I/O system 5.2 BYT driver UCMODE (Unit Control Code) Bit Designation Meaning 15 DP 0 = no duplex mode 1 = with duplex mode 14 x reserved 13 HB 0 = no history memory 1 = with history memory 12 LF 0 = CR without LF 1 = CR followed by LF 11 UC 10 UC 9 UC 8 UC 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 7 PB ID for interpretation of a parameter block. 0 = unrestricted interpretation 1 = restricted or no interpretation 6 TI 5 TO 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 4 IP 3 OP 2 ST 1 CT 0 MD ID for unit type 00 = I/O device (always specify this ID for EGA units!) 01 = output device 10 = input device 11 = reserved 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 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! RMOS3 V3.50 Reference Manual Part II 144 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 145 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II 146 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 147 Functions and configuration of the basic I/O system 5.2 BYT driver Bit Designation Meaning 15 UN 14 UN 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. 13 SD Scroll screen SD = 0: activate SD = 1: deactivate 12 EI Emulation EE = 0: activate EE = 1: deactivate 11 SP Start Page: page displayed at startup. This page must be the same for all units. 10 SP 9 WP 8 WP 7 D1 Input D1 = 0: enable D1 = 1: disable 6 D0 Output D0 = 0: enable D0 = 1: disable 5 TU Number of the unit the keyboard is assigned to (0 `number of units') 4 TU 3 AU 2 AU 1 DP 0 DP Current write page (page 0 ... page 3) 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. RMOS3 V3.50 Reference Manual Part II 148 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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 0 1 2 1 2 0 2 0 1 ... ... ... 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 149 Functions and configuration of the basic I/O system 5.2 BYT driver 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 specifies 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 (EBX register) interim buffer prior to task start 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. RMOS3 V3.50 Reference Manual Part II 150 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver MODEXT (extended modes) This byte is used to set further modes of the BYTE driver. Bit Designation Meaning 7 x Reserved (0) 6 x 5 T1 Selection of the control character table for adaptation to the terminal type: 4 T0 00: Table 0 01: Table 1 10: Table 2 11: Table 3 3 x 2 x 1 RQX Reserved (0) 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 151 Functions and configuration of the basic I/O system 5.2 BYT driver 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 0 Data port PRTDAT 1 Command port PRTCMD 2 Extra port 2 PORT_2 3 Extra port 3 PORT_3 4 Status port PRTSTA or offset for PRTDAT. Bit 14: Bit 15: 0 Value is output. 1 Value is read (certain controllers are initialized by reading registers). 0 Bits 8 to 13 are interpreted as ID. 1 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 ports (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). RMOS3 V3.50 Reference Manual Part II 152 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver Bit Designation Meaning 7 BC Background color 6 BC 5 BC 4 BC 3 FC 2 FC 1 FC 0 FC Foreground color dec hex Foreground color Background color Flashing 0 0 Black Black no 1 1 Blue Blue no 2 2 Green Green no 3 3 Cyan Cyan no 4 4 Red Red no 5 5 Magenta Magenta no 6 6 Brown Yellow no 7 7 Light gray White no 8 8 Dark gray Black Yes 9 9 Light blue Blue Yes 10 A Light green Green Yes 11 B Light green Cyan Yes 12 C Light red Red Yes 13 D Light magenta Magenta Yes 14 E Yellow Yellow Yes 15 F White 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). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 153 Functions and configuration of the basic I/O system 5.2 BYT driver Note For EGA units: Observe the information provided 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 BS 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 LF 0AH Line feed RMOS3 V3.50 Reference Manual Part II 154 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 155 Functions and configuration of the basic I/O system 5.2 BYT driver 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 */ }; RMOS3 V3.50 Reference Manual Part II 156 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 157 Functions and configuration of the basic I/O system 5.2 BYT driver 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 RMOS3 V3.50 Reference Manual Part II 158 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.2 BYT driver 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). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 159 Functions and configuration of the basic I/O system 5.3 CRT driver 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. RMOS3 V3.50 Reference Manual Part II 160 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 161 Functions and configuration of the basic I/O system 5.3 CRT driver 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, pState pParam bit 3..0 Function code of the selected driver function Status pointer that reports internal states of the driver. Points to a data block with other functionspecific parameters. RMOS3 V3.50 Reference Manual Part II 162 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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 7 Function 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 163 Functions and configuration of the basic I/O system 5.3 CRT driver 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 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 0000 0000H reserved 1 -4 -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. RMOS3 V3.50 Reference Manual Part II 164 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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 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 20 1 Description Note 1 1 Length of the input buffer or transformation table 20 Total scope 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 165 Functions and configuration of the basic I/O system 5.3 CRT driver 5.3.3.2 Release unit (CRT_RELEASE) Opcode: Parameter block: 01H None CRT_RELEASE 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 Parameter block: 20 bytes CRT_READ 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 Line feed (only in line feed mode) CR (0DH) LF (0AH) RMOS3 V3.50 Reference Manual Part II 166 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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: 5.3.3.4 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. Write (CRT_WRITE) Opcode: Parameter block: 03H 20 bytes CRT_WRITE 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 POINTER far 0 Address of the output buffer Note 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: Parameter block: 04H 20 bytes CRT_WRITE This function is identical with opcode 03. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 167 Functions and configuration of the basic I/O system 5.3 CRT driver 5.3.3.6 Read character in transparent mode (CRT_ONE_XREAD) Opcode: Parameter block: 05H None CRT_ONE_XREAD 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: Parameter block: 06H 20 bytes CRT_WRT_XREAD 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 POINTER far 0 Address of the output buffer Note 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. RMOS3 V3.50 Reference Manual Part II 168 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 5.3.3.8 Write and read (CRT_WRT_READ) Opcode: Parameter block: 07H 20 bytes CRT_WRT_READ 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: Parameter block: 08H 20 bytes CRT_SKIP_LINE 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). 5.3.3.10 Type Offset Description POINTER far 0 reserved WORD int 6 Number of carriage returns/line feeds POINTER far 10 reserved WORD int 16 reserved Note Form feed/clear screen (CRT_FORM_FEED) Opcode: Parameter block: 09H none CRT_FORM_FEED 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 169 Functions and configuration of the basic I/O system 5.3 CRT driver 5.3.3.11 Read character in transparent mode (CRT_HSFS_XREAD) Opcode: Parameter block: 0AH 20 bytes CRT_HSFS_XREAD 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: 5.3.3.12 Type Offset Description Note POINTER far 0 Address of the input buffer WORD int 6 reserved POINTER far 10 reserved WORD int 16 reserved Write character (CRT_HSFS_WRITE) Opcode: Parameter block: 0BH 20 bytes CRT_HSFS_WRITE This function transfers a single character to the output unit. The parameter block to initialize prior to the call has the following structure: Type 5.3.3.13 Offset Description Note POINTER far 0 Address of the output character WORD int 6 reserved POINTER far 10 reserved WORD int 16 reserved Redefine unit (CRT_CREATE_NEW) Opcode: Parameter block: 0CH 20 bytes CRT_CREATE_NEW 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 RMOS3 V3.50 Reference Manual Part II 170 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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 ASCII 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 ASCII 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 (^) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 171 Functions and configuration of the basic I/O system 5.3 CRT driver 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: 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 5.3.4.2 Parallel driver This value is occupied during system configuration. 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 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) UNS 8 short Task ID of the task started after an unexpected input (0FFFFH if none) PORT 10 Note 1 Driver-specific data (120/246 bytes) 256 Total 1 See Interrupt routines of the CRT2 driver. (Page 177) RMOS3 V3.50 Reference Manual Part II 172 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 173 Functions and configuration of the basic I/O system 5.3 CRT driver UCMODE (Unit Control Code) Bit Designatio n 15 Meaning reserved 14 13 12 LF 0 = CR without LF 1 = CR followed by LF 11 UC 10 UC 9 UC 8 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 7 x 6 x 5 x 4 x 3 x 2 x 1 x 0 MD reserved 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 DATA IN reset) CMD STS 8255 with HW strobe DATA OUT CMD STS - - CMD STS 8250 DATA MODEM CTRL LINE CTRL INTR ENABLE LINE STS RMOS3 V3.50 Reference Manual Part II 174 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 175 Functions and configuration of the basic I/O system 5.3 CRT driver In addition, the CRT2 driver sets the following values at status field XSTATUS: char XSTATUS + 00: DRIVER ID char XSTATUS + 01: DEVICE ID char XSTATUS + 02: 00H char XSTATUS + 03: 00H char XSTATUS + 04: Start character char XSTATUS + 05: 00H char XSTATUS + 06: 00H char XSTATUS + 07: 00H EAX register EBX register 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. RMOS3 V3.50 Reference Manual Part II 176 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.3 CRT driver 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 - RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 177 Functions and configuration of the basic I/O system 5.4 RAM disk driver 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. RMOS3 V3.50 Reference Manual Part II 178 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.4 RAM disk driver 5.4.1.1 Sequence of the RmIO system call 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 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. RmGetFlag 5.4.1.2 Opcodes of the RAM DISK driver The RAM driver executes the following opcodes. 00H Reserve RAM DISK 01H Release RAM DISK 02H Read logical block 03H Write logical block 04H Dummy operation 05H Read logical blocks 06H Write logical blocks 07H reserved 08H reserved 09H reserved 0AH reserved 0BH reserved 0CH reserved 0DH reserved 0EH I/O control 0FH reserved On detection of an invalid opcode, the driver stops execution of the I/O request and returns an error code (-1) in the primary status byte. For more information on the handling of opcodes, refer to the reference manual. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 179 Functions and configuration of the basic I/O system 5.4 RAM disk driver 5.4.2 RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: 5.4.2.1 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 Function parameter This parameter selects the relevant RAM driver operation (bits 0 to 3) and also controls the operational sequence. Bit Values 7 Function Preemptive bit 0 Sort I/O request based on priority 1 Set I/O request to the start of the queue 6 Wait bit 0 No waiting 1 Wait for completion of the I/O operation 5, 4 reserved 3..0 00H..06H Valid opcode 07H..0DH reserved 0EH Valid opcode 0FH reserved Opcode (bits 0 to 3) The RAM driver executes the following function codes. 00H Reserve RAM DISK 01H Release RAM DISK 02H Read logical block 03H Write logical block 04H Dummy operation 05H Read logical blocks 06H Write logical blocks 07H reserved RMOS3 V3.50 Reference Manual Part II 180 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.4 RAM disk driver 08H reserved 09H reserved 0AH reserved 0BH reserved 0CH reserved 0DH reserved 0EH I/O control operation 0FH reserved On detection of an invalid opcode, the driver stops execution of the I/O request and returns an error code (-1) in the primary status byte. 5.4.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 RAM 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. 1 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 00H 0000H 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 reserved/not reserved. -12 00H 0000H 0000 0000H Configuration error 1 If a configuration error is detected, the RAM driver disables the 02H and 06H operations until the error is cleared, for example, by means of I/O control operation 0EH. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 181 Functions and configuration of the basic I/O system 5.4 RAM disk driver 5.4.2.3 Parameter pParam SVC RmIO uses parameter pParam to pass a pointer to a 14-byte field (parameter block). This field must be initialized prior to the call, depending on the selected driver operation (e.g. read logical block). Always set the reserved parameters in the parameter block to zero. Parameter block for read/write operations: 1 Parameters Offset Type Description RAM_LBA 0 DWORD long Logical block address RAM_BUF_ADR 4 POINTER far Read/write buffer address 1 RAM_NUM_BLK 10 WORD int Number of logical blocks 14 Total scope The drivers always use the same selector to execute I/O operations, which means that changes to the selector are ignored in the case of an offset overrun. Example of the parameter block in ASM386: RAM_RWPB STRUC RAM_LBA DD ? RAM_BUF_ADR %dp ? RAM_NUM_BLK %wd ? RAM_RWPB ENDS RWPB RAM_RWPB <> Example of the parameter block in C: typedef struct ram_rwpb { unsigned long RAM_LBA; unsigned void *RAM_BUF_ADR; unsigned int RAM_NUM_BLK; } RAM_RWPB; RAM_RWPB rwpb; Parameter block for I/O control operations: Parameters Offset Type Description SUBFUNCT 0 WORD short Sub-operation code COUNT 2 WORD short reserved BUFFER 4 POINTER far I/O buffer address RESERVED 10 WORD int reserved 14 Total scope RMOS3 V3.50 Reference Manual Part II 182 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.4 RAM disk driver Example of the parameter block in ASM386: RAM_IOPB STRUC SUBFUNCT DW ? COUNT DW ? BUFFER %dp ? RESERVED %wd ? RAM_IOPB ENDS IOPB RAM_IOPB <> Example of the parameter block in C: typedef struct ram_iopb { unsigned short SUBFUNCT; unsigned short COUNT; unsigned void *BUFFER; unsigned int RESERVED; }RAM_IOPB; RAM_IOPB iopb; 5.4.3 Opcodes 5.4.3.1 Reserve RAM DISK (00H) Opcode: Parameter block: 00H None This operation reserves the unit (RAM DISK) specified in the RmIO (unit_id) exclusively for I/O requests of the calling task. I/O requests of other tasks are accepted, but only executed after 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: 1. Calls with set preemptive bit in chronological order. 2. Calls of the task that has reserved the unit in chronological order. 3. 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. 5.4.3.2 Release RAM DISK (01H) Opcode: Parameter block: 01H None This operation revokes the reservation of the unit (RAM DISK) 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 183 Functions and configuration of the basic I/O system 5.4 RAM disk driver 5.4.3.3 Read logical block (02H) Opcode: Parameter block: 02H 14 bytes This operation passes one logical block from a RAM DISK to a read buffer. The logical block is read starting at the logical block address specified in the parameter block. Parameter block: Parameters Offset Type Description RAM_LBA 0 DWORD long Logical block address RAM_BUF_ADR 4 POINTER far Read buffer address RAM_NUM_BLK 10 WORD int reserved 14 Total scope The address of the read buffer points to the memory area to which the data is written. The operation is terminated with error code (-1) in the primary status byte if an incorrect logical block address is specified. 5.4.3.4 Write logical block (03H) Opcode: Parameter block: 03H 14 bytes This operation passes one logical block from a write buffer to a RAM DISK. The logical block is written starting at the logical block address specified in the parameter block. Parameter block: Parameters Offset Type Description RAM_LBA 0 DWORD long Logical block address RAM_BUF_ADR 4 POINTER far Write buffer address RAM_NUM_BLK 10 WORD int reserved 14 Total scope The write buffer contains the data to transfer. The I/O operation is terminated with error code (-1) in the primary status byte if an incorrect logical block address is specified. 5.4.3.5 Dummy operation (04H) Opcode: Parameter block: 04H None This operation has no effect and is only implemented for reasons of RMOS3 compatibility. RMOS3 V3.50 Reference Manual Part II 184 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.4 RAM disk driver 5.4.3.6 Read logical blocks (05H) Opcode: Parameter block: 05H 14 bytes This operation transfers one or several logical blocks from a a RAM DISK to a read buffer. The blocks are read contiguously, starting at the logical block address specified in the parameter block. Parameter block: Parameters Offset Type Description RAM_LBA 0 DWORD long Logical block address RAM_BUF_ADR 4 POINTER far Read buffer address RAM_NUM_BLK 10 WORD int Number of logical blocks 14 Total scope The address of the read buffer points to the memory area to which the data is written. If you have set the zero value for the number of blocks to read, the operation is successfully completed without processing. The operation is terminated with error code (-1) in the primary status byte if an incorrect logical block address or number of blocks is specified. 5.4.3.7 Write logical blocks (06H) Opcode: Parameter block: 06H 14 bytes This operation transfers one or several logical blocks from a write buffer to a RAM DISK. The blocks are written contiguously, starting at the logical block address specified in the parameter block. Parameter block: Parameters Offset Type Description RAM_LBA 0 DWORD long Logical block address RAM_BUF_ADR 4 POINTER far Write buffer address RAM_NUM_BLK 10 WORD int Number of logical blocks 14 Total scope The write buffer contains the data to transfer. If you have set the zero value for the number of blocks to write, the operation is successfully completed without processing. The operation is terminated with error code (-1) in the primary status byte if an incorrect logical block address or number of blocks is specified. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 185 Functions and configuration of the basic I/O system 5.4 RAM disk driver 5.4.3.8 I/O control operation (0EH) Opcode: Parameter block: 0EH 14 bytes This operation is used to call sub-operations for the I/O control function. The general parameter block of the I/O control operation has the following structure: Parameters Offset Type Description SUBFUNCT 0 WORD short Sub-operation code COUNT 2 WORD short reserved BUFFER 4 POINTER far I/O buffer address RESERVED 10 WORD int reserved 14 Total scope The following sub-operations can be selected for the I/O control function: 00H Read operating parameters 01H Redefine operating parameters All other sub-operations are reserved. Read operating parameters Sub-operation code: Parameter block: 00H 14 bytes This sub-operation reads the current operating parameters of a unit assigned to the RAM driver to an input buffer. Transfer the address of the input buffer in the parameter block. Parameter block: Parameters Offset Type Description SUBFUNCT 0 WORD short 00H COUNT 2 WORD short reserved BUFFER 4 POINTER far Address of the input buffer RESERVED 10 WORD int reserved 14 Total scope The structure of the operating parameters read correspond to the driver-specific parameters in the UCD block, starting at parameter UCD.START to UCD.RAM_SPEC (cf. UCD description in the System Manual). RMOS3 V3.50 Reference Manual Part II 186 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.4 RAM disk driver Redefine operating parameters Sub-operation code: Parameter block: 01H 14 bytes This sub-operation can be used to redefine the current operating parameters of a unit assigned to the RAM driver. The parameters are fetched from a 12-byte output buffer. Transfer the address of the output buffer in the parameter block. Parameter block: Parameters Offset Type Description SUBFUNCT 0 0 WORD short 00H COUNT 2 2 WORD short reserved BUFFER 4 4 POINTER far Address of the output buffer RESERVED 10 10 WORD int reserved 14 14 Total scope The structure of the parameters in the output buffer corresponds to the driver-specific parameters in the UCB block, starting at parameter UCD.START to UCD.RAM_SPEC (cf. description of the unit control table UCD, chapter "Unit control data table (UCD) (Page 188)"). 5.4.4 Configuration 5.4.4.1 Driver control data (DCD) table 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 char if none) 0FFH 1 INIT Entry point of the initialization routine in the driver void NEAR * X_RAM_INIT SVC RIO-SVC entry point for drivers void NEAR * X_RAM_SVC_BR FLAGS Driver flags: char 2H Bit0=1: Parallel drivers Bit1=1: Type II driver Bit2=0: Initialization in the boot sequence 1 FMAX Maximum function code for type II driver char 0EH RESERV 2 reserved bytes char 00H, 00H This value is occupied during the system configuration. The DCD block of the RAM DISK driver is defined in the I/O configuration in the "Device definitions" area using C function RcInitRamdisk(). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 187 Functions and configuration of the basic I/O system 5.4 RAM disk driver 5.4.4.2 Unit Control Data table The UCD block (Unit Control Data table) has a general and a driver-specific part. For information about the parameters of the general part, refer to the System manual, chapter 2.3.10 "Unit Control Data table (UCD)". The general part of the UCD block has the following structure: General parameters in the UCD block 1 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) UNS 8 short Task ID of the task started after an unexpected input PORT 10 1 Driver-specific data (120/246 bytes) Set this value to -1, because the RAM driver does not support a task start triggered by unexpected interrupt. Driver-specific parameters in the UCD block Parameters Offset Type Description START 0 void FAR * Start address of the RAM Disk NBLK 6 unsigned Number of blocks BLKLEN 8 short Block length RAM_MODE 10 char Access mode RAM_SPEC 11 char reserved (0) 12 reserved up to 256 The driver-specific parameters are available as of PORT in the UCD block. Reserved bits of a parameter must always be set to zero. The meaning of the parameters is defined in the following sections. START (start address) Parameter START is used to specify the start address of the RAM DISK. NUMBLK ( number of blocks) Parameter NUMBLK is used to specify the length of the RAM DISK in blocks of the length BLKLEN. BLKLEN (block length) The length of a block in bytes is specified in parameter BLKLEN. Set a fixed block length of 512 bytes to enable the use of the RAM driver by the HSFS. RMOS3 V3.50 Reference Manual Part II 188 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.4 RAM disk driver RAM_MODE (access mode) Parameter RAM_MODE is defined as follows: Bit Designatio n Meaning 7 0 reserved (0) 6 0 5 0 4 Phy Start address of the RAM DISK 0 = as selector/offset 1 = as absolute address 3 0 reserved (0) 2 0 1 0 0 0 Bit 4 of parameter RAM_MODE is used to define whether the RAM driver interprets start address START as absolute address, or as selector/offset. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 189 Functions and configuration of the basic I/O system 5.5 DMA driver 5.5 DMA driver 5.5.1 Properties 5.5.1.1 Functionality of the DMA driver Basic initialization of all configured DMA channels Channel-specific DMA transfer (write, read) Abortion of a DMA transfer Providing status information in the DMA parameter block about transfer activities 5.5.1.2 Note for use as subprogram The DMA driver does not participate in the system sequence (exception: basic initialization by means of X_DM2_INIT) until called by a different driver running in RMOS3. In the stack, RMOS3 drivers (S state) that need the DMA driver must pass a pointer (FAR) to the DMA parameter block and then call the DMA entry point address (FAR) with public symbol X_DM2_DRIVER. Since the DMA driver is programmed in C, no register contents of the caller will be saved for the use as subprogram. This means that a driver written in ASM must backup the registers by itself. 5.5.1.3 Special features of the DMA controller 80C206 (PC) Implementation is essentially based on the restrictions imposed by PC-compatible hardware: Maximum block size of a transfer is 64 KB DMA transfers can only be executed within the first 16 MB of the address space. You don't need to take care of actions when segment limits are exceeded during the DMA transfer. A DMA -transfer may never exceed a physical 64KB segment limit. The DMA driver prevents this by requesting a dynamic interim buffer at the time of initialization. The length of this buffer is specified in the driver SW configuration and may not be exceeded in DMA mode, for otherwise it is possible that memory contents are overwritten. The DMA driver verifies the parameters of a READ/WRITE request in terms of compliance with segment limits (transfer address plus count) and, if necessary, executes the transfer using the buffer. RMOS3 V3.50 Reference Manual Part II 190 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.5 DMA driver No interrupt of the DMA controller on completion of the DMA transfer, if the specified number of transfers has been completed. This means that READ/WRITE requests to the DMA controller must always be completed with an ABORT request. This ensures that the transfer data is transferred from the buffer to the calling source. It is presumed that the user of the DMA controller knows when an initiated DMA transfer is concluded (e.g. by means of interrupt of the requesting I/O module). Memory to memory DMA transfers are not supported. Only channel 3 of controller block 1 is currently supported. The data width is 8 bits. 5.5.2 RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: Function, pState bit 3..0 Function code of the selected driver function Status pointer that reports internal states of the driver. pParam 5.5.2.1 Points to a data block with other functionspecific parameters. Function parameter This parameter sets the selected DMA driver functions (bit 0..3) and controls the sequence of the driver function. Bit Values 7 Preemptive bit 0 Sort I/O request based on priority 1 Set I/O request to the start of the queue 6 Wait bit 0 No waiting 1 Wait for completion of the I/O operation 5 reserved 4 3..0 Function reserved 00H..05H Valid opcode 06H..0FH reserved RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 191 Functions and configuration of the basic I/O system 5.5 DMA driver Opcode (bits 0 to 3) The DMA driver executes the following function codes, depending on the configured unit type (see UCD.TYPE). 00H Reserve unit 01H Release unit 02H Read (from buffer to unit) 03H Write (from unit to buffer) 04H Cancel transmission (read or write) 05H Redefine unit On detection of an invalid function code, the DMA 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. 5.5.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 DMA driver. 1 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 00H 0000H 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 reserved/not reserved. -3 00H 0000H 0000 0000H I/O request terminated due to timeout -4 1 1 0000 0000H I/O request terminated by transfer abort function Insignificant; undefined value RMOS3 V3.50 Reference Manual Part II 192 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.5 DMA driver 5.5.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 DMA driver function (e.g. read). The respective meaning of the bytes of the parameter block is explained in the description of DMA driver functions. Always set reserved parameters to zero. Type Offset Description WORD short 0 Reserved POINTER far 2 Offset/segment of the DMA transfer buffer DWORD long 8 Size of the DMA transfer buffer in bytes. WORD short 12 DMA transfer status POINTER far 14 Offset/segment, or physical device address 20 Total scope 5.5.3 Opcodes 5.5.3.1 Reserve unit (DMA_RESERVE) Opcode: Parameter block: Note 00H 14 or 20 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. I/O requests with set preemptive bit form the 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. The parameter block for a reservation request must have the following structure: Type Offset Description WORD short 0 reserved POINTER far 2 reserved WORD short 8 Timeout value (multiple of 256 ms) WORD short 10 reserved WORD short 12 DMA transfer status POINTER far 14 reserved Note 1 2 1 Only taken into account if a timeout monitoring function is specified in UCD.CONTROL. 2 Only taken into account if an extension of the DMA I/O parameter block is specified in UCD.CONTROL. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 193 Functions and configuration of the basic I/O system 5.5 DMA driver 5.5.3.2 Release unit (DMA_RELEASE) Opcode: Parameter block: 01H 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. The DMA driver automatically releases a reservation on timeout. 5.5.3.3 Read from memory (DMA_READ) Opcode: Parameter block: 02H 14 or 20 bytes This function transfers data from a user-defined buffer (RAM) to a DMA unit. Parameter block for read request: 1 5.5.3.4 Type Offset Description Note WORD short 0 reserved POINTER far 2 Address of the transfer buffer DWORD long 8 Length of the DMA transfer in bytes WORD short 12 DMA transfer status POINTER far 14 Offset/segment, or physical device address 1 Only taken into account if an extension of the DMA I/O parameter block is specified in UCD.CONTROL. Write to memory (DMA_WRITE) Opcode: Parameter block: 03H 14 or 20 bytes This function transfers data from a DMA unit to a user-defined buffer (RAM). Parameter block for write request: 1 Type Offset Description Note WORD short 0 reserved POINTER far 2 Address of the transfer buffer DWORD long 8 Length of the DMA transfer in bytes WORD short 12 DMA transfer status POINTER far 14 Offset/segment, or physical device address 1 Only taken into account if an extension of the DMA I/O parameter block is specified in UCD.CONTROL RMOS3 V3.50 Reference Manual Part II 194 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.5 DMA driver 5.5.3.5 Transmission abortion (DMA_ABORT) Opcode: Parameter block: 4H 14 or 20 bytes This function aborts the DMA transfer by initiating the reset of the corresponding DMA channel by the DMA unit. This action aborts an active DMA operation for a write or read request (initiated with RmIO) and returns the error code (-4). Parameter block for abortion request: 1 5.5.3.6 Type Offset Description WORD short 0 reserved POINTER far 2 reserved DWORD long 8 Length of the DMA transfer in bytes at the time of abortion WORD short 12 DMA transfer status POINTER far 14 reserved Note 1 Only taken into account if an extension of the DMA I/O parameter block is specified in UCD.CONTROL. Redefine unit (DMA_CREATE) Opcode: Parameter block: 05H 1216 bytes This function provides the option of redefining a unit that is assigned to the DMA driver, or to read the current parameter definition. This means that it is possible to run a re-initialization while the sequence is active. Parameter block for re-initialization: Type Offset Description Note POINTER far 0 Address of the input buffer 2 POINTER far 6 Address of the initialization buffer 3 WORD short 12 Length of the input buffer 1 WORD short 14 DMA transfer status 1 Only taken into account if an extension of the DMA I/O parameter block is specified in UCD.CONTROL. 2 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 of the input buffer, a maximum of 23 words is copied from the corresponding UCB parameters. The program first executes the copy request if a simultaneous re-initialization request is pending. 3 The initialization buffer must have the same structural arrangement and size with regard to the DMA-specific data table as provided for the unit control data table (UCD). The structure begins with UCD.TYPE. The initialization function is discarded if the offset and segment value of this address equal zero RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 195 Functions and configuration of the basic I/O system 5.5 DMA driver 5.5.3.7 Subprogram calls of the DMA driver Parameter transfer Before the DMA driver is called with entry point address X_DM2_DRIVER by a driver running in RMOS3, a DMA I/O parameter block must be defined accordingly and transferred with a pointer (segment: offset) in the stack. The DMA driver clears the stack on completion of the process. The calling program must ensure that the registers are backed up. DMA I/O parameter block I/O parameter block: Parameters Offset Type Description DMA_UNIT 0 BYTE char DMA channel ID DMA_FUNCT 1 BYTE char DMA function DMA_OFFSET 2 WORD int DMA transfer address (offset) DMA_SELECTOR 6 WORD short DMA transfer address (selector) DMA_CNT_LOW 8 WORD short Number of DMA transfers (least significant count) DMA_CNT_HIGH 10 WORD short Number of DMA transfers (most significant count) DMA_STATUS 12 WORD short DMA transfer status 14 Total Structure with extension configured in UCD.CONTROL: Parameters Offset Type Description DMA_UNIT 0 BYTE char DMA channel ID DMA_ACK_OFF 14 WORD int DMA acknowledge address (least significant value/offset) DMA_ACK_SEL 18 WORD short DMA acknowledge address (most significant value/selector) 20 Total DMA channel ID (DMA_UNIT) This parameter defines the ID (device ID) of the specific DMA channel at which the DMA operation is to be executed (valid range of values: 0..255). The assignment of a DMA channel ID that was not defined in the software configuration triggers an error message in the DMA status field. Note The specific DMA channel ID corresponds to the configured device ID for the DMA driver, but not to the channel number of the individual DMA control blocks. This means the devices assigned for the DMA driver in the UCD block successively correspond to DMA channel ID 0 to 1. RMOS3 V3.50 Reference Manual Part II 196 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.5 DMA driver DMA function (DMA_FUNCT) This parameter is used to specify the DMA operation. The following opcodes are defined for the DMA driver: 00 Reserved for future extensions 01 Reserved for future extensions 02 Read (from memory) 03 Write (to memory) 04 Abort (read/write operation) Note: If an incorrect opcode is used for this DMA driver, a parameter error message is returned in the DMA status field (DMA_STATUS). DMA transfer address (DMA_SELECTOR / DMA_OFFSET) These two parameters define a pointer to the DMA transfer address (selector/offset) as of which a DMA operation (read, write) is to be executed. However, the DMA driver internally uses a converted physical address relation ( >= 20-bit address). Number of DMA transfers (DMA_CNT_LOW / DMA_CNT_HIGH) Parameter DMA_CNT_LOW (least significant transfer counter) is used to instruct the DMA driver to transfer a specific number of bytes in the DMA operation (read, write). 64 KB are transferred if DMA_CNT_LOW is set to 0. Parameter DMA_CNT_HIGH (most significant transfer counter) must be set to zero for the 82C206 Am 9517A and 80186/188 DMA control blocks, because a maximum block length of 64 KB (16-bit value) can be transferred: Otherwise, a range error is returned in the DMA transfer status and the DMA operation is discarded. Parameter DMA_CNT_HIGH is only included for DMA control with 82258 (ADMA) and 82380. If a feedback of the current transfer length for the abort function was selected in the parameter for the I/O process (UCD.CONTROL), it must be taken into account that the abort function has the additional effect that the DMA_CNT_LOW/DMA_CNT_HIGH parameters are assigned the current transfer length at the time of abortion (feedback). Note In an active DMA operation that was initiated with RmIO, the feedback is generated in the parameter block of the DMA operation to be aborted (parameter overwrite), and in all other situations in the parameter block of the abort function (feedback). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 197 Functions and configuration of the basic I/O system 5.5 DMA driver DMA transfer status (DMA_STATUS) The DMA I/O parameter block contains a status field that returns information about the progress of the transfer operation. The most significant byte is reserved for future versions (value=0), while the least significant byte is encrypted with a binary code as follows: Bit Designatio n Meaning 7 0 reserved (value 0) 6 x Abort function could not be executed (no busy job) 5 x General transfer error (job discarded) 4 x Transfer counter >= 64 KB (job rejected) 3 x Configuration error (job cannot be processed) 2 x Invalid DMA function (job rejected) 1 x Invalid DMA channel ID (job rejected) 0 x DMA channel is BUSY (job is still busy) DMA acknowledge address (DMA_ACK_OFF/DMA_ACK_SEL) The DMA driver only interprets these parameters if an extension was defined for the corresponding DMA unit with regard to the DMA I/O parameter block in configuration parameter UCD.CONTROL. In this case, the DMA_ACK_OFF and DMA_ACK_SEL parameters specify the acknowledge address range for a memory/memory DMA operation (read, write). Meaning of these parameter values, depending on the interpretation configured in UCD.CONTROL: 1. Logical address relation (selector/offset) DMA_ACK_OFF = offset value DMA_ACK_SEL = segment value 2. Physical address relation (32-bit address/48-bit address) DMA_ACK_OFF = least significant address (bit 0 to bit 31) DMA_ACK_SEL = most significant address (bit 32 to bit 47) RMOS3 V3.50 Reference Manual Part II 198 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.5 DMA driver 5.5.3.8 Program call (X_DM2_DRIVER) Example of the program call of the DMA driver from a driver that is running in RMOS3 (S state) without extended parameter block. ASM386: EXTRN X_DM2_DRIVER :FAR DMA_IOPB STRUC DMA_UNIT DB ? ; UNIT ID DMA_FUNCT DB ? ; FUNCTION MODE DMA_OFFSET DW ? ; BUFFER OFFSET DMA_SELECTOR DW ? ; BUFFER SELECTOR DMA_CNT_LOW DW ? ; COUNTER LOW DMA_CNT_HIGH DW ? ; COUNTER HIGH DMA_STATUS DW ? ; STATUS DMA_IOPB ENDS DMA_DRV_DS SEGMENT RW PUBLIC DM2_IOPB DMA_IOPB <> ; DMA-I/O-PARAMETERBLOCK DMA_DRV_DS ENDS ASSUME DS: DMA_DRV_DS %RCODE_SEG MOV DM2_IOPB.DMA_UNIT, <UNIT ID> MOV DM2_IOPB.DMA_FUNCT, <FUNCTION MODE> MOV DM2_IOPB.DMA_OFFSET, <BUFFER OFFSE> MOV DM2_IOPB.DMA_SELECTOR, <BUFFER SELECTOR> MOV DM2_IOPB.DMA_CNT_LOW, <COUNTER> MOV DM2_IOPB.DMA_CNT_HIGH, 0 MOV EAX, OFFSET DM2_IOPB PUSH DS PUSH EAX CALL X_DM2_DRIVER .... %END_RCODE_SEG C: extern void near x_dm2_driver (void far *); typedef struct dma_iopb { unsigned char DMA_UNIT; unsigned char DMA_FUNCT; void far *DMA_BUFFER; unsigned long DMA_COUNT; unsigned short DMA_STATUS; } IOPB_DMA; unsigned short enter_dma() { IOPB_DMA dm2_iopb; dm2_iopb DMA_UNIT = <DMA-UNIT ID>; dm2_iopb DMA_FUNCT = <DMA-FUNCTION MODE>; dm2_iopb DMA_BUFFER = <DMA-BUFFER ADDRESS>; dm2_iopb DMA_COUNT = <DMA-COUNTER>; dm2_iopb DMA_STATUS = 0; x_dm2_driver (&dm2_iopb); return (dm2_iopb.DMA_STATUS); } RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 199 Functions and configuration of the basic I/O system 5.6 FD0 driver 5.6 FD0 driver 5.6.1 Properties For the following floppy drives The floppy driver supports 3.5" and 5.25" drives with the following formats: 360 K floppy disk in 5.25" drive (low density) 360 K floppy disk in 5.25" drive (high density) 1.2 MB floppy disk in 5.25" drive (high density) 720 K floppy disk in 3.5" drive (low density) 1.44 MB floppy disk in 3.5" drive (high density) Accessing floppy disks preferably by means of CRUN call Floppy disks can be accessed for read/write operations by means of driver calls. You should preferably work with CRUN calls to retain the DOS-compatible data format. CRUN calls will also ensure the portability of programs. The floppy driver can manage a maximum of two floppy disk controller interfaces, each with two drives. The IBM-AT register set is interpreted for floppy disk control. Static or dynamic parameters The drive parameters can be set by means of corresponding configuration data (permanent), or by means of IOCTL function (dynamic). Initialization in BIOS The BIOS EPROM routines are prerequisite for initialization; support of the SETUP functions is not provided. The FD0 floppy disk driver is a type II driver. The control is handled by means of PC/AT- compatible floppy disk controller. Data is transferred using the DMA control performed by the driver. The driver operates in block-oriented mode with logical data block length of 512 bytes. You can avoid system deadlocks by setting a timeout monitor for the driver operations. The timeout period can be configured. It is also possible to repeat commands in error case. You can specify the number of retries. The operating parameters of the floppy drives can be read, deleted and redefined at runtime. This facilitates the support of different floppy formats on the same floppy drive. RMOS3 V3.50 Reference Manual Part II 200 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver You may also use the FD0 driver to format floppy disks. For this purpose, the driver needs to be assigned pool memory space. This memory is returned to the pool on completion of the formatting process. The FD0 driver automatically positions the read/write head, which means that you can dispense with positioning prior to read/write/format operations. 5.6.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 returns a corresponding error code. 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 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. RmGetFlag 5.6.1.2 Opcodes of the FD0 driver The FD0 driver executes the following opcodes. More information about driver operations and their programming is provided in the next chapters. 00H Reserve unit 01H Release unit 02H Read logical block 03H Write logical block 04H Format floppy disk 05H Read logical blocks 06H Write logical blocks 08H Position to track 09H Position to track 0 0AH Get drive status 0BH Remove drive parameters (delete) 0CH Define drive parameters (create) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 201 Functions and configuration of the basic I/O system 5.6 FD0 driver 5.6.2 RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: Function, Function, pState bit 5 Cancel bit bit 3..0 Function code of the selected driver function Status pointer that reports internal states of the driver. pParam 5.6.2.1 Points to a data block with other functionspecific parameters. Function parameter This parameter selects the relevant FD0 driver operation (bits 0 to 3) and also controls the operational sequence. Bit Values 7 Preemptive bit 0 Sort I/O request based on priority 1 Set I/O request to the start of the queue 6 Wait bit 0 No waiting 1 Wait for completion of the I/O operation 5 Cancel bit 0 Data in interim buffer is valid 1 Data in interim buffer is invalid 4 3..0 Function reserved 00H..0CH Valid opcode 0DH..0FH reserved Cancel bit (bit 5) This bit is only evaluated if the buffer mode is activated (at parameter UCD.TYPE (drive type)). Before the driver runs the I/O operation, it flags invalid data in the unit-specific interim buffer if the cancel bit is set. The next (usually current) read request with a length of one block (opcode 02) resets the internal flag and reads the entire track (including the logical block) from the floppy to the interim buffer. RMOS3 V3.50 Reference Manual Part II 202 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver Opcode (bits 0 to 3) The FD0 driver executes the following opcodes, depending on the configured unit type (see UCD.TYPE). The first two function codes are basically identical for all drivers. 00H Reserve drive 01H Release drive 02H Read logical block 03H Write logical block 04H Format floppy disk 05H Read logical blocks 06H Write logical blocks 07H reserved 08H Position to track 09H Position to track 0 0AH Get drive status 0BH Delete drive configuration parameters 0CH Create drive configuration parameters 0DH-0FH reserved On detection of an invalid (reserved) function code, the FD0 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. 5.6.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 receiving module/controller-specific information returned after the I/O operation was aborted, or after a DMA error) for the FD0 driver. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 203 Functions and configuration of the basic I/O system 5.6 FD0 driver 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 00H 1) 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 reserved/not reserved. -3 00H 0000H 0000 0000H I/O request terminated due to timeout -4 1) 1) 0000 0000H reserved -5 00H 7H 0000H 0000 0000H I/O request aborted due to I/O error -6 00H 0000H 0000 0000H DMA error -7 1) 0000H 0000 0000H Pool/configuration error -8 1) 0000H 0000 0000H Delete/create error; unit not ready/available 1) 1) see FD0 device status/NEC status (corresponds to the 3rd/4th status word of variable xxxx) Status messages for all functions, except reserve/release drive: Byte Bit 7 6 5 4 3 2 1 0 NOT RDY TIME RETRY 0 PROT 00 Primary status byte 01 0 02 FD01 STS-0 (NEC status register 0) 03 FD01 STS-1 (NEC status register 1) 0 POOL Status information: Byte 00 Primary status byte Byte 01 Secondary status byte Byte 02,03 2. status word FD0 unit status in secondary status byte: POOL Out of memory pool, or no additional buffer memory for read request NOTRDY Unit (drive) not ready TIME Timeout RETRY Retry error PROT Write protected floppy disk RMOS3 V3.50 Reference Manual Part II 204 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver 2. Status word (least significant byte) The status of NEC status register 0 is entered in this byte Bit Name Meaning 6,7 INT CODE Interrupt code 00 Normal Termination of Command 01 Abrupt Termination of Command (started but not completed) 02 Invalid Command Issue (command not started) 03 reserved 5 SEEK END 1 If the drive has executed the SEEK command. 4 EQUIPMENT 1 If track 0 signal after 77 step pulses not CHECK active 3 NOT READY 1 If the drive is not ready 2 HEAD ADDRESS Indicates the head status during interrupt 1 UNIT SELECT 1 1 If drive 1 is selected 0 UNIT SELECT 0 1 If drive 0 is selected 2. status word (most significant byte) The status of NEC status register 1 is entered in this byte 5.6.2.3 Bit Name Meaning 15 END OF CYLINDER 1 14 --- reserved 13 DATA ERROR 1 On CRC error If the controller was not operated within the specified period. If the controller attempts to access a further sector after the last one. 12 OVERRUN 1 11 --- reserved 10 NO DATA 1 If the controller could not find the sector. 9 NOT WRITABLE 1 If the controller attempts to access a write protected floppy disk. 8 MISSING ADDR. MARK 1 If the controller cannot find an address mark ID. Parameter pParam Parameters Offset Type Description FD_LBA 0 DWORD long Logical block address FD_ADR 4 POINTER far Write/read buffer address FD_NB 10 WORD int Number of logical blocks 14 Total scope RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 205 Functions and configuration of the basic I/O system 5.6 FD0 driver FD_LBA This parameter is used to specify the logical block address of the first block to address. FD_ADR The address of the read or write buffer for data transmission is entered in this parameter. FD_NB This parameter specifies the number of logical blocks to transfer in succession. (This value is also used as timeout factor). Values not used in the parameter block must be set to zero. Example of the parameter block in ASM: FD_IOPB FD_LBA FD_ADR FD_NB FD_IOPB IOPB STRUC DD ? %dp ? DW ? ENDS FD_IOPB <> 5.6.3 Opcodes 5.6.3.1 Reserve unit (FD2_RESERVE) Opcode: Parameters required: 00H none This operation 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. 5.6.3.2 Release unit (FD2_RELEASE) Opcode: Parameter required: 01H none This operation 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. The FD0 driver automatically releases a reservation on timeout. RMOS3 V3.50 Reference Manual Part II 206 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver 5.6.3.3 Read logical block (FD2_READ_1) Opcode: Necessary parameters: 02H FD_LBA, FD_ADR This operation reads the data of a logical block from the floppy disk, starting at logical block FD_LBA, and transfer this data to memory. FD_ADR contains the start address of the memory area to which the data is read. 5.6.3.4 Write logical block (FD2_WRITE_1) Opcode: Necessary parameters: 03H FD_LBA, FD_ADR This operation reads the data of a logical block from memory to a floppy disk, starting at logical block FD_LBA. FD_ADR contains the start address of the memory area from which the data is read. 5.6.3.5 Format floppy disk (FD2_FORMAT) Opcode: Parameter required: 04H none This operation is used to format all tracks of a floppy disk. The format derived from the write operation is defined by the UCD UCD.TYPE, UCD.SELECT, UCD.CONTROL, UCD.MAX_TRACK, UCD.MAX_SEC_N, UCD.MAX_SEC_0, and UCD.FORMAT parameters. The FD0 driver requests 512 bytes of memory from the pool specified in parameter UCD.POOLID to execute the operation. If RMOS3 is unable to provide the requested memory pool, the format operation is aborted with primary status value (-7). Note The requested memory pool is returned to RMOS3 on completion/abortion of the format operation. 5.6.3.6 Read logical blocks (FD2_READ) Opcode: Necessary parameters: 05H FD_LBA, FD_ADR, FD_NB This operation reads the number of logical blocks specified in FD_NB from the floppy disk to system memory, starting at logical block FD_LBA. The length of the data block may be a multiple integer of the sector length specified in the UCD block for the respective drive. The number of sectors to transfer is specified in FD_NB of the parameter block. FD_LBA contains the logical block address of the first block. The FD0 driver converts the specified number internally into track, sector and side numbers that describe the first sector from which data is to be transferred. The sectors are processed based on their ascending number, independent of their physical position in terms of the floppy track and side. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 207 Functions and configuration of the basic I/O system 5.6 FD0 driver Parameter FD_ADR contains the start address of the memory area to which the data is to be read. With zero value at parameter FD_NB, the I/O request is successfully completed without processing. 5.6.3.7 Write logical blocks (FD2_WRITE) Opcode: Necessary parameters: 06H FD_LBA, FD_ADR, FD_NB This operation reads the number of data blocks specified in FD_NB from system memory and transfers these as of logical block FD_LBA to a floppy disk (drive). The length of the data block may be a multiple integer of the sector length specified in the UCD block for the respective drive. The number of sectors to transfer is specified in FD_NB of the parameter block. Parameter FD_ADR contains the start address of the memory area that contains the data to transfer. 5.6.3.8 Position to track (FD2_SEEK) Opcode: Necessary parameters: 08H FD_LBA This operation positions the read/write head to the track that the FD0 driver determines based on the logical block address (FD_LBA). The controller does not verify consistency between the new track number and the value specified in the sector ID field. It is therefore possible to position read/write head on a nonformatted floppy. 5.6.3.9 Position to track 0 (FD2_RECA) Opcode: Parameter required: 09H none This operation resets the read/write head to track 0. 5.6.3.10 Get drive status (FD2_UNIT_RDY) Opcode: Necessary parameters: 0AH FD_ADR This operation reads the configuration parameters of the specified drive and saves these to user memory as of address FD_ADR. The configuration contains the UCD parameters UCD.TYPE, UCD.SELECT, UCD.CONTROL, UCD.MAX_TRACK, UCD.MAX_SEC_N, UCD.MAX_SEC_0, UCD.MAX_RETRY, UCD.FORMAT, and UCD.TIME_OUT. RMOS3 V3.50 Reference Manual Part II 208 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver 5.6.3.11 Remove drive parameters (delete) (FD2_DELETE) Opcode: Parameter required: 0BH none This operation removes (deletes) the specified drive from further processing. All future I/O requests related to the corresponding drive will be aborted with parameter error (-1) until the configuration has been redefined. This procedure facilitates dynamic changes to drive parameters. If the addressed drive is still in use by a task at the time of the operation call, the drive parameters are not removed and error code (-8) is returned. 5.6.3.12 Define drive parameters (create) (FD2_CREATE) Opcode: Necessary parameters: 0CH FD_ADR This operation creates the drive parameters of an undefined drive and conditions these for controller access. Input parameter FD_ADR points to a drive-specific data block that has the same components as the UCD block. If an attempt is made to create an existing drive, or specify a parameter block that does not have the selected structure format, the FD01 driver terminates the operation with error code (-8). Otherwise, the drive parameters are entered in the corresponding UCB block to define the drive for future I/O requests. Drive-specific data block Parameters Offset Type Description TYPE 00 WORD Drive type SELECT 02 WORD Drive control CONTROL 04 WORD Drive control mode MAX_TRACK 06 WORD Number of tracks per side MAX_SEC_N 08 WORD Number of sectors/track 1..n MAX_SEC_0 10 WORD Number of sectors/track 0 MAX_RETRY 12 WORD Retry factor FORMAT 14 WORD Format: Fill byte/interleave factor TIME_OUT 16 WORD Timeout value in milliseconds RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 209 Functions and configuration of the basic I/O system 5.6 FD0 driver 5.6.4 Configuration 5.6.4.1 Driver control data (DCD) table The DCD block of the FD0 driver is defined in the I/O configuration in the "Device definitions" area using C function RcInitFD0(). 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_FD0_INIT SVC RIO-SVC entry point for driver void NEAR * X_FD0_SVC_BR FLAGS Driver flags: char 2H Bit0=1: Parallel driver Bit1=1: Type II driver Bit2=0: Initialization in the boot sequence 1 5.6.4.2 FMAX Maximum function code for type II driver char 02H RESERV 2 reserved bytes char 00H, 00H This value is occupied during the system configuration. Unit Control Data (UCD) table 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 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) 2 PORT 10 256 Note Driver-specific data (120/246 bytes) Total 1 See Interrupt routines of the FD0 driver. 2 Set this value to -1, because the FD0 driver does not support a task start triggered by unexpected interrupt RMOS3 V3.50 Reference Manual Part II 210 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver Driver-specific parameters in the UCD block The driver-specific parameters are stored in the UCD block as of offset 10. Drive-related parameters: Parameters Offset Type Description TYPE 10 short Drive type CONTROL 12 short Drive control CONTROL 14 short Drive control mode MAX_TRACK 16 int Number of tracks per side MAX_SEC_N 20 int Number of sectors track 1..N MAX_SEC_0 24 int Number of sectors track 0 MAX_RETRY 28 short Retry factor FORMAT 30 short Format: Fill byte/interleave factor TIME_OUT 32 int Timeout value per block BOARD 36 int Module ID Module-related parameters: Parameters Offset Type Description COUNT_HL 28 short Head positioning time COUNT_ML 30 short Motor activation time COUNT_RL 32 short Motor startup time DMA_PAGE 34 short DMA page port address DMA_BASE 36 short DMA base port address FDC_BASE 38 short FDC port base address DMA_ID 40 short reserved (0FFFFH) POOL_ID 42 short Memory pool ID 254 short Not used from 44 to 126 (254) Note The declaration of module-related parameters is optional for all successive units (drives) that use the same module ID. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 211 Functions and configuration of the basic I/O system 5.6 FD0 driver Drive type (TYPE) The drive type defines specific parameters of a floppy drive. The FD0 driver provides fixed parameter values for this purpose: Bit Designation Meaning 15 I reserved (0) 14 BM 13 T2 12 SE 11 ST 10 ST 9 SG 8 SG 7 SLN 6 SLN Sector length track 1..N 10 = 512 bytes/sector 5 SLO 4 SLO Sector length track 0 10 = 512 bytes/sector 3 DS Floppy size 0 = Standard (8") 1 = Mini (3.5" and 5.25") 2 D1 Write density track 1..N 1 = double write density 1 D0 Write density track 0 1 = double write density 0 N Number of sides 0 = one 1 = two Drive control (SELECT) This parameter specifies drive-related control values: Meaning of the bits for control register 1: Bit Designation Meaning 7 D reserved (0) 6 B 5 H 4 L 3 FD 2 FD 1 FD 0 FD Selection of assigned drives 0001 = drive 0 0010 = drive 1 Meaning of the bits for control register 2: The most significant byte of SELECT must be initialized to zero for the FD0 driver. RMOS3 V3.50 Reference Manual Part II 212 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver Drive control mode (CONTROL) This parameter determines the drive-related control and monitoring values. Except bits 14 and 15, all bits are reserved (null) for the FD0 driver. The parameter is coded as follows: Bit Designation Meaning 15 HD High Density Format 0 = off 1 = on 14 DEL Doubling the scan steps 0 = off 1 = on 13 0 reserved (0) 12 0 11 0 10 0 9 0 8 0 7 0 6 0 5 0 4 0 3 0 2 0 1 0 0 0 Comments related to CONTROL: Bit 14 reduces drive control to half of the track density (parameter MAX_TRACK must be set accordingly). This means that the track scan is executed based on twice the number of scan steps (STEP). A drive with 80 tracks can therefore be set up to IBM format with 40 tracks. You also need to set bit 15 if using drives with high density format. Number of tracks (MAX_TRACK) The parameter defines the number of tracks per floppy side. The capacity of double-sided floppy disks compared to single-sided floppy disks is not doubled by doubling the number of tracks, but rather by doubling the sectors per track. The value specifies the number of tracks per single-sided and double-sided floppy disk (valid range of values: 1..255). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 213 Functions and configuration of the basic I/O system 5.6 FD0 driver Number of sectors/track 1..N (MAX_SEC_N) The parameter defines the number of sectors/track in the track range 1..N, with N representing the largest possible track (MAX_TRACK-1) per floppy disk side. For doublesided recording, the factual possible number of sectors/track is calculated by doubling MAX_SEC_N (valid range of values: 1..255). Number of sectors for track 0 (MAX_SEC_0) The parameter defines the number of sectors on track 0. For double-sided recording, the number of possible sectors on track 0 is calculated by doubling MAX_SEC_0 (range of values: 1..255). Retry factor (MAX_RETRY) This parameter is used to define the maximum number of retries of an operation in error case. Least significant byte Contains the maximum number of retries (0 to 255) for operations with DMA operations (READ/WRITE). Recommended value = 2 Retries are executed at status value: - LOST DATA - CRC ERROR - RECORD NOT FOUND - WRITE FAULT Most significant byte Contains the maximum number of retries (0 to 255) for operations with search operations (SEEK/RECA) Recommended value = 1 Retries are executed at status value: - CRC ERROR - SEEK ERROR Note If the timeout utility is activated, take into account that it is also possible to execute the selected number of retries within the specified maximum time, without having terminated the operations with timeout (depending on the drive type and timer clock). Formatting mode (FORMAT) The least significant byte of this parameter defines the fill value that is used for the data area of the sector during formatting. The most significant byte contains the interleave factor for floppy formatting. A parameter value 0 or 1 defines no interleaving, which means that the track sectors are numbered in physical order (1..MAX_SEC). RMOS3 V3.50 Reference Manual Part II 214 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.6 FD0 driver Example: Sector numbering for 8 sectors/track with interleave factor: Interleave factor Sector sequence 1 1 2 3 4 5 6 7 8 2 1 5 2 6 3 7 4 8 3 1 4 7 2 5 8 3 6 4 1 3 5 7 2 4 6 8 Timeout value (TIME_OUT) The least significant byte of this parameter defines the timeout to use. This value is interpreted as multiple of 256 ms and defines the maximum interval that may expire before a floppy I/O operation is terminated with error code (-3). The value zero at this parameter deactivates the timeout utility. Any other value specifies the maximum time per logical block (sector) for block-oriented operations, or per track for track-oriented commands in units of 256 ms. The most significant byte is reserved and must be set to zero value. Module ID (BOARD) This parameter defines the ID of the corresponding PC drive controller (FD0) that is assigned this unit. Head load time (COUNT_HL) The HEAD LOAD TIME represents the time it takes the drive control to lower the read/write head. Enter the time values in milliseconds. You may set times from 1 ms to 65535 ms. A value of 35 ms is used by default. Motor runtime (COUNT_ML) Motor runtime in milliseconds. You can set values from 1 ms to 65535 ms. (Default: 6000 ms for FD0 drivers). Motor startup time (COUNT_RL) Motor startup time in milliseconds. You can set values from 1 ms to 65535 ms. A value of 800 ms is used by default. DMA_PAGE The value set at this parameter defines the DMA page port address used. DMA_BASE This value contains the DMA base port address. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 215 Functions and configuration of the basic I/O system 5.6 FD0 driver FDC_BASE This word contains the FDC base port address. DMA_ID Reserved (must be set to 0FFFFH). Memory pool ID (POOL_ID) This parameter is used to to assign the FD0 driver a memory pool ID for requesting a data range of sufficient length for the format operation (512 bytes). Note In buffer mode, memory pool requirements are increased by the drive-related buffer range. 5.6.4.3 Interrupt routines of the FD0 driver The FD0 driver provides an entry point address for its interrupt handler, which is declared as PUBLIC symbol with the following meaning: X_FD0_INTR entry point address for FDC interrupt requests of AT-compatible controller module. 5.6.4.4 Stack requirements of the FD0 driver S state 30 words I state 34 words DI state 0 RMOS3 V3.50 Reference Manual Part II 216 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver 5.7 HD0 driver 5.7.1 Properties Pre-configured in the RMOS3 nucleus HD driver HD0 is pre-configured for RMOS3 systems. Access by means of CRUN Hard disks can be accessed for read/write operations by means of driver calls. You should preferably work with CRUN calls to retain the DOS-compatible data format. CRUN calls will also ensure the portability of programs. Functions The IBM-AT register set is interpreted for HD control. The following functions are supported: management of up to 3 drives The system supports EIDE HDs to ATA-3 standard. Support for LBA mode Support for 32-bit data transfer Support for 2 IDE controllers (primary and secondary channel) Static or dynamic parameters Drive parameters can be set by means of configuration data (permanent setting) and using the RmCreateUnit function (dynamic setting). Initialization in BIOS The BIOS EPROM routines are prerequisite for initialization; support of the SETUP functions is not provided. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 217 Functions and configuration of the basic I/O system 5.7 HD0 driver 5.7.1.1 Area of application and opcode Overview The HD0 driver is a serial mass storage volume driver. The control is handled by means of PC/AT-compatible HD controller. The HD controller is capable of managing up to 2 HD controller adapters, each with two drives. Opcode The following operation codes (bit 0 ... bit 3) are executed by the HD0 driver: 00H Reserve drive 01H Release drive 02H Read logical block 03H Write logical block 04H Format hard disk 05H Read logical blocks 06H Write logical blocks 07H Reserved 08H Reserved 09H Reserved 0AH Read drive configuration parameters 0BH Delete drive configuration parameters 0CH Create drive configuration parameters 0DH Reserved 0EH Reserved 0FH Reserved On detection of an invalid opcode, the HD0 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.7.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 pState Function code of the selected driver function pParam Points to a data block with other function-specific parameters. Status pointer that reports internal states of the driver. RMOS3 V3.50 Reference Manual Part II 218 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver 5.7.2.1 Function parameter This parameter selects the HD0 driver operation (bit 0 to 3) and controls the sequence of the driver function. Bit Values 7 Function Preemptive bit 0 Sort I/O request based on priority 1 Set I/O request to the start of the queue 6 Wait bit 0 No waiting 1 Wait for completion of the I/O operation 5 Cancel bit (drive-oriented) 0 Valid data in interim buffer 1 Invalid data in interim buffer 4 - reserved 3..0 00H..0DH Valid opcode 0EH..0FH reserved Cancel bit (bit 5) You can set the cancel bit for a drive to reset the internal flag that indicates that data is already available in the drive-related memory space (i.e. an identical or a successive read request for a block leads to repeated physical access to the floppy disk). Opcode (bits 0 to 3) The HD0 driver executes the following opcodes. 00H Reserve drive 01H Release drive 02H Read logical block 03H Write logical block 04H Format hard disk 05H Read logical blocks 06H Write logical blocks 07H Reserved 08H Reserved 09H Reserved 0AH Read drive configuration parameters 0BH Delete drive configuration parameters 0CH Create drive configuration parameters 0DH Reserved 0EH Reserved 0FH Reserved RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 219 Functions and configuration of the basic I/O system 5.7 HD0 driver On detection of an invalid opcode, the HD0 driver stops execution of I/O requests and returns an error code (-1) in the primary status byte. For more information about the opcodes, refer to the next chapter. 5.7.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 HD0 driver. If several RmIO calls are processed simultaneously (bit 6 in parameter Function), each call must have a separate status field for returning the parameters. Primary status byte Secondary status byte 2nd status word Meaning 0 00H 0000H I/O request is queued. 1 00H 0000H Busy processing the I/O request. HD0 status HDC status I/O request successfully completed. -1 00H 0000H I/O request rejected due to invalid parameterization -2 00H 0000H Reserve/release operation was not executed, because the unit is already/not reserved HD0 Status HDC Status I/O request terminated due to timeout value -4 00H 0000H Reserved -5 HD0 Status HDC Status I/O request aborted due to I/O error HD0 Status HDC Status I/O request aborted due to DMA error HD0 Status 0000H I/O request aborted due to pool/configuration error HD0 Status 0000H Delete/create error; unit not ready/available 2 1) -3 -6 -7 -8 1) 1) 1) 1) 1) 1) 1) 1) 1) 1) See the following tables The 3rd and 4th status word are always 0000H. RMOS3 V3.50 Reference Manual Part II 220 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver Status messages for all operations with the exception of "Reserve unit" or "Release unit": Byte Bit 7 6 5 4 3 2 1 0 POOL NOTRDY TIME RETRY 0 0 00 Primary status byte 01 0 02 HD status register 03 Operation status value 0 STATUS information: BYTE 00 = primary status byte BYTE 01 = secondary status byte BYTE 02 = content of the status register after an operation BYTE 03 = additional operation-related status value Information for the secondary status byte: POOL = required memory pool size not available NOTRDY = unit not available (drive disabled) TIME = timeout RETRY = retry error Information for HD status registers: 2nd Status word (least significant byte) Bit Meaning 7 1: UNIT BUSY 6 1: UNIT READY 5 1: WRITE FAULT 4 1: SEEK COMPLETE 3 1: DATA REQUEST (DRQ) 2 1: ECC CORRECTION 1 1: INDEX 0 1: STATUS ERROR RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 221 Functions and configuration of the basic I/O system 5.7 HD0 driver Information for additional operations status (BIOS-compatible) in 2nd status word (most significant byte): 5.7.2.3 FFH = Not implemented E0H = Status error (error register = 0) CCH = Write error BBH = Undefined error AAH = Drive not ready 80H = Monitoring timeout (READY/DRQ) 04H = Positioning error 20H = Controller error 11H = Corrected data error 10H = Invalid ECC byte when reading 0BH = Not implemented 0AH = Invalid sector flag detected 09H = Segment exceeded in data transmission 07H = Initialization error 05H = Reset error (RESET) 04H = Requested sector not found 02H = Incorrect address mark 01H = Invalid operation, or operation parameter not in valid range 00H = No additional operation status (no error) Parameter pParam SVC RmIO uses parameter pParam to pass a pointer to a 10-byte parameter block. Example of the parameter block in ASM: HD01_IOPB STRUC HD01_LBA DD ? HD01_ADR %DP ? HD01_NB DW ? HD01_IOPB ENDS IOPB HD01_IOPB <> HD01_LBA Dword for the logical block address HD01_ADR The address (segment, offset) of the write/read buffer for data transmission is entered at this parameter HD01_NB This word specifies the number of logical blocks to transfer in succession. (This word is also used as timeout factor). RMOS3 V3.50 Reference Manual Part II 222 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver 5.7.3 Opcodes 5.7.3.1 Reserve unit (00H) Opcode: Parameters required: 00H none This operation 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 the 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. 5.7.3.2 Release unit (01H) Opcode: Parameter required: 01H none This operation 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. The HD0 driver automatically releases a reservation on timeout. 5.7.3.3 Read logical block (02H) Opcode: Necessary parameters: 02H HD01_LBA, HD01_ADR This operation reads the data of a logical block from the HDD, starting at logical block HD01_LBA, and transfer this data to memory. HD01_ADR contains the start address of the memory area to which the data is read. 5.7.3.4 Write logical block (03H) Opcode: Necessary parameters: 03H HD01_LBA, HD01_ADR This operation reads the data of a logical block from memory to a HDD, starting at logical block HD01_LBA. HD01_ADR contains the start address of the memory area from which the data is fetched. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 223 Functions and configuration of the basic I/O system 5.7 HD0 driver 5.7.3.5 Format hard disk (04H) Opcode: Parameter required: 04H none This operation is used to format all HD tracks. The respective interleave format that is derived from the write operation is defined by the parameters of the UCD block. In order to execute the operation, the HD0 driver requests a memory pool from RMOS3, which it uses to build a table that contains all information for formatting a track. This memory pool has a length of 512 bytes. If RMOS3 is unable to provide the requested memory pool, the format operation is aborted with primary status value (-7). Note: The requested memory pool is returned to RMOS3 on completion/abortion of the format operation. 5.7.3.6 Read logical blocks (05H) Opcode: Necessary parameters: 05H HD01_LBA, HD01_ADR, HD01_NB This operation reads the number of logical blocks specified in HD01_NB from the hard disk to system memory, starting at logical block HD01_LBA. The data block to transfer has a length of 512 bytes. The number of sectors to transfer is specified in HD01_NB of the parameter block. HD01_LBA contains the logical block address of the first block. The HD0 driver converts the specified number internally into cylinder, sector and head numbers that describe the first sector from which data is to be transferred. The sectors are processed based on their ascending number, independent of their physical position in terms of the HD track. Parameter HD01_ADR contains the start address of the memory area to which the data is to be read. With zero value at parameter HD01_NB, the I/O request is successfully completed without processing. 5.7.3.7 Write logical blocks (06H) Opcode: Necessary parameters: 06H HD01_LBA, HD01_ADR, HD01_NB This operation reads the number of data blocks specified in HD01_NB from system memory and transfers these as of logical block HD01_LBA to a HD. The data block to transfer has a length of 512 bytes. The number of sectors to transfer is specified in HD01_NB of the parameter block. Parameter HD01_ADR contains the start address of the memory area that contains the data to transfer. This operation positions the read/write head to the cylinder that the HD0 driver calculates based on the logical block address (HD01_LBA). RMOS3 V3.50 Reference Manual Part II 224 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver 5.7.3.8 Read drive parameters (0AH) Opcode: Necessary parameters: 0AH HD01_ADR This operation reads the configuration parameters of the specified drive and saves these to user memory as of address HD01_ADR ab. The configuration data contains the UCD parameters TYPE_MODE, TYPE_ID, HDPARAM, MAX_CYL, MAX_SEC, MAX_HEAD, PRE_CYL, POS_CYL, CONTROL, FORMAT, UCD.FORMAT, TIME_OUT, and MAX_RETRY (see drive-specific UCD parameters). 5.7.3.9 Remove drive parameters (delete or dismount) (0BH) Opcode: Parameter required: 0BH none This operation removes (deletes) the specified drive from further processing. All future I/O requests related to the corresponding drive will be aborted with parameter error (-1) until the configuration has been redefined. This procedure facilitates dynamic changes to drive parameters. If the addressed drive is still in use by a task at the time of the operation call, the drive parameters are not removed and error code (-8) is returned. 5.7.3.10 Define drive parameters (create or mount) (0CH) Opcode: Necessary parameters: 0CH HD01_ADR This operation creates the drive parameters of an undefined drive and conditions these for controller access. Input parameter HO01_ADR points to a drive-related parameter block that has the same structure as the UCD block. If an attempt is made to create an existing drive, or specify a parameter block that does not have the selected structure format, the HD0 driver terminates the operation with error code (-8). Otherwise, the drive parameters are entered in the corresponding UCB block to define the drive for future I/O requests. Drive-specific parameter block: Parameters Offset Type Description TYPE_MODE 00 BYTE Drive_mode TYPE_ID 01 BYTE Drive type HDPARAM 02 PTR Pointer to drive Parameter table MAX_CYL 06 WORD Maximum number of cylinders MAX_SEC 08 BYTE Maximum number of sectors/track MAX_HEAD 09 BYTE Maximum number of heads/cylinder PRE_CYL 10 WORD Start cylinder pre-compensation POS_CYL 12 WORD Cylinder for parking position CONTROL 14 BYTE Drive control value FORMAT 15 BYTE Interleave factor/track TIME_OUT 16 BYTE Timeout value MAX_RETRY 17 BYTE Maximum number of retries RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 225 Functions and configuration of the basic I/O system 5.7 HD0 driver 5.7.4 Configuration 5.7.4.1 Driver control data (DCD) table 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_HD0_INIT SVC RIO-SVC entry point for driver void NEAR * X_HD0_SVC_BR FLAGS Driver flags: char 2H Bit0=1: Parallel driver Bit1=1: Type II driver Bit2=0: Initialization in the boot sequence 1 FMAX Maximum function code for type II driver char 0DH RESERV 2 reserved bytes char 00H, 00H This value is occupied during the system configuration. The DCD block of the HD0 driver is defined in the I/O configuration in the "Device definitions" area using C function RcInitHD0(). 5.7.4.2 Unit Control Data (UCD) table 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) 2 PORT 10 Driver-specific data (120/246 bytes) 1 See Interrupt routines of the HD0 driver. 2 Set this value to -1, because the HD0 driver does not support a task start triggered by unexpected interrupt. RMOS3 V3.50 Reference Manual Part II 226 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver 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. 5.7.4.3 Driver-specific parameters in the UCD block a) Drive-oriented parameters (LUN) Parameters Offset Type Description TYP_MODE 10 char Drive mode TYPE_ID 11 char Drive type HDPARAM 12 void FAR * Drive parameter address MAX_CYL 18 short Number of cylinders MAX_SEC 20 char Number of sectors/track MAX_HEAD 21 char Number of heads/cylinder PRE_CYL 22 short Start cylinder for pre-compensation POS_CYL 24 short Cylinder number of the parking position for transport (home position) CONTROL 26 char Drive control value FORMAT 27 char Formatting mode (interleave) TIME_OUT 28 char Timeout value MAX_RETRY 29 char Retry factor in error case BOARD 30 short Module ID b) Module-oriented parameters (HD adapter) Parameters Offset Type Description COUNT_RDY 32 short Time to wait for transfer readiness COUNT_DRQ 34 short Time to wait for DRQ DISK_REG 36 short HD register DMA_PAGE 38 short Parameter is not evaluated DMA_BASE 40 short Parameter is not evaluated BASE_HDC 42 short HDC base port address DMA_ID 44 short DMA channel ID POOL_ID 46 WORD short Memory pool ID 48 WORD short Not used from 44 (48) to 126 (254) Note The declaration of module-related parameters is optional for all successive units (drives) that use the same module ID. The driver-specific parameters are stored in the UCD block as of offset 8. The meaning of the various parameters is documented in the following sections. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 227 Functions and configuration of the basic I/O system 5.7 HD0 driver Drive mode (TYPE_MODE) The drive type defines specific parameters of a hard disk. The HD0 driver interprets this parameter as follows: Bit Designatio n Meaning 7 x Buffer mode Selection for block-oriented reading of a complete track to a drive-related memory buffer 6 0 reserved (0) 5 0 4 x Drive selection 0 = drive 1 1 = drive 2 3 x 2 x 1 x Step rate time 0000 = 35 s xxxx = 0.5 ms units 0 x Notes on TYPE_MODE: The step rate time defines the time required for track-to-track positioning. The corresponding value is derived from the data sheets of the drives used. Bit 7 can be used to select a buffer mode for block-oriented read operations. This means that the read request of a block with specific logical block address in buffer mode starts an operation for reading the entire information from the corresponding track to a drivespecific memory area. Successive read requests having logical block addresses containing the same track ID are then provided with the data already read from the driverelated buffer without physical HD access. In buffer mode, the HD0 driver needs a corresponding buffer for the drive that is requested in the init process (or CREATE) by means of the allocated pool ID. The necessary buffer length is derived from: (block length) * (number of sectors/track) The block always has a length of 512 bytes. This operation is discarded if it is not possible to provide the necessary buffer length. Note Allocated memory space is released by running operation 11 (delete drive parameters). RMOS3 V3.50 Reference Manual Part II 228 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver Drive type (TYPE_ID) This parameter defines a HD type containing values that represent the interpretation for drive-related parameters (HDPARAM, MAX_CYL, MAX_SEC, MAX_HEAD, PRE_CYL, POS_CYL and CONTROL): Value = 0: No drive parameter table available (HDPARAM=0); the values defined for drive-related parameters will be used. Value = 1 to 254: The HD type is known and the pointer to a defined ROM-resident Drive parameter table is stored in the UCD block of the HDPARAM component. The drive-related parameters are provided with values from the dive parameter table by means of type-specific index (INDEX=(TYPE_ID-1)*16). Value = 255: The HD type is unknown. The corresponding drive-related parameters are undefined (value = 0) and must be specified using operation 13 (CMOS RAM). Drive parameter address If the drive type parameter (TYPE_ID) contains a value between 1 and 254, parameter HDPARAM must point to a ROM-resident drive parameter table containing at least 15 field entries (each of a length of 16 bytes) having the following structures: Offset Type Description 0 short Number of cylinders (1 to 4096) 2 short Number of heads (1 to 16) 4 short Not used 6 short Start cylinder for pre-compensation 7 char Not used 8 char Control value (more than 8 heads) 9 char Not used 10 char Not used 11 char Not used 12 short Cylinder for head parking position 14 char Number of sectors/track (1 to 64) 15 char Reserved The ROM-resident drive parameters are usually stored in the BIOS of the corresponding PC/AT. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 229 Functions and configuration of the basic I/O system 5.7 HD0 driver Number of cylinders (MAX_CYL) This parameter defines the maximum number of cylinders of a HD (valid range of values: 1...4096). Number of sectors/track (MAX_SEC) This parameter defines the maximum number of sectors/track (valid range of values: 1...64). Number of heads/cylinder (MAX_HEAD) Defines the maximum number of read/write heads on a HD; i.e. the number of disk surfaces that can be used per cylinder (valid range of values: 1...16). Start cylinder for pre-compensation (PRE_CYL) This parameter defines the start cylinder for write pre-compensation (valid range of values: 0...N-1, N= MAX_CYL; write pre-compensation is discarded if -1 is set). Cylinder for head parking position (POS_CYL) This parameter defines a cylinder as protective measure for head positioning to prevent damage to the drive by head crashes during transport. (valid range of values: 0...4095). Drive control value (CONTROL) This parameter defines specific HD operations and is coded as follows: Bit Designatio n Meaning 7 x 6 x Command repetition 00 = retry on error xx = no retries 5 0 Not evaluated 4 0 3 x ID of number of heads > 8 0 = greater than or equal to 8 1 = greater than 8 2 0 Not evaluated 1 0 0 0 RMOS3 V3.50 Reference Manual Part II 230 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver Formatting mode (FORMAT) The formatting mode defines the interleave factor to be used for track formatting. Interleaving is discarded if parameter value 0 or 1 is set, which means that the track sectors (start value=1) are numbered in physical order (1..MAX_SEC). Example: Sector numbering for 17 sectors/track with interleave factor: 1 2 3 4 Interleave sector 1 1 1 1 Sector sequence 2 10 7 14 3 2 13 10 4 11 2 6 5 3 8 2 6 12 14 15 7 4 3 11 8 13 9 7 9 5 15 3 10 14 4 16 11 6 10 12 12 15 16 8 13 7 5 4 14 16 11 17 15 8 17 13 16 17 6 9 17 9 12 5 Timeout value (TIME_OUT) This value defines the maximum interval that may expire before a HD I/O operation is terminated with error code (-3). The value of this parameter is interpreted as multiple of 256 ms. The value zero at this parameter deactivates the timeout utility. Any other value specifies the maximum time per logical block (sector) for block-oriented operations, or per track for track-oriented commands in units of 256 ms (range of values 0...255). Retry factor (MAX_RETRY) This parameter is used to define the maximum number of retries of an operation in error case. The retry factor relates to all read/write operations and to positioning operations with corresponding error-related status evaluation (range of values: 0...15). Note If the timeout utility is activated, take into account that it is also possible to execute the selected number of retries within the specified maximum time, without having terminated the operations with timeout. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 231 Functions and configuration of the basic I/O system 5.7 HD0 driver Module ID (BOARD) This parameter defines the drive-related ID for a HD control module (adapter). All of the following module-dependent parameters are assigned to this ID. The HD0 driver is capable of managing up to 2 HD control modules; the corresponding parameter value is set to 0 or 1. Time to wait for ready state (COUNT_RDY) The most significant byte of the parameter contains the maximum time to wait for the ready state (RDY) at startup (power-on/reset). The time value is specified in units of 256 ms (valid range of: 0...255). The default value is zero. The least significant byte of the parameter contains the maximum time to wait for the ready state (RDY) in normal operation (after startup). The time value is specified in units of 256 ms (valid range of: 0...255). The default value is zero. Time to wait for transfer readiness (COUNT_DRQ) The least significant byte of the parameter contains the maximum time to wait for transfer readiness (DRQ) for data output from the CPU to a HD. The time value is specified in units of 256 ms (valid range of: 0...255). The default value is zero. The most significant byte is reserved (value = 0). HD register address (DISK_REG) This parameter defines the port address for the HD register (03F6H or 0376H) to be used. The HD register serves to control drives with more than 8 heads, or to suppress operation retries in error case. The content of parameter CONTROL is used as control value. DMA page port address (DMA_PAGE) This parameter is not evaluated. DMA base port address (DMA_BASE) This parameter is not evaluated. HDC base port address (BASE_HDC) This parameter defines the base port address of the HD controller used. The base port address for IBM-compatible HD controller modules (adapters) is defined for the primary setting with value 1F0H and for the secondary setting with value 170H. RMOS3 V3.50 Reference Manual Part II 232 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.7 HD0 driver DMA channel ID (DMA_ID) This parameter must be set to -1 (no DMA support). Memory pool ID (POOL_ID) The parameter is used to assign the HD0 driver a memory pool ID that can be used for the following memory requests: For operation 04 (format drive) the unit in state "no buffer memory available" needs 512 bytes of data memory building track-related formatting data. This memory is returned to RMOS3 on completion of the operation. Operation 04 is not supported if the memory request fails. A memory request is discarded in "buffer memory available" state, because the existing buffer memory will be used for the formatting data. In the initialization phase, or for operation 12 (define drive parameters) and buffer mode configuration in parameter TYPE_MODE, drive-related data memory with a length of MAX_SEC * 512 bytes is requested for interim storage of all track data. This buffer memory is released with operation 11 (delete drive parameters). Buffer storage is not supported if RMOS3 is out of sufficient buffer memory. In this situation, the unit remains in "no buffer memory available" state. 5.7.4.4 Interrupt routines of the HD0 driver The HD0 driver provides an entry point address for its interrupt handlers, which are declared as PUBLIC symbol with the following meaning: X_HD0_INTR entry point address for interrupt requests of the IBM AT HD control module 5.7.4.5 Stack requirements of the HD0 driver S state 30 words I state 34 words DI state 0 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 233 Functions and configuration of the basic I/O system 5.8 COM driver 5.8 COM driver 5.8.1 Properties Driver for host-to-host communication The type I COM driver is used for host-to-host communication in half duplex mode. Data is transmitted via serial interface (e.g. V.24). The COM driver can be customized to suit the requirements of all standard I/O modules (e.g. 8250, 8251A, 8530) and is used to control up to 255 units. The COM driver supports the 3964 standard protocol. Hardware requirements The COM driver needs an additional cyclic interrupt-triggering timer to execute protocolcontrolled time monitoring functions (see section "Signal sequences (Page 236)"). A 10 ms timer interrupt is required for the first device unit of the COM driver, independent of the number of device units. 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. Data transmission interface The data can be transmitted optionally via V.24/V.28 or 20 mA interface. 5.8.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 specified at 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. RMOS3 V3.50 Reference Manual Part II 234 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver Host to host communication always runs in half duplex mode, while send and receive I/O requests are managed or enabled simultaneously (full duplex mode). This means that the COM driver can redirect its operation to an active send or receive request in case of an initiation conflict (both hosts simultaneously start a send or receive request). In order to complete read operations (i.e. on receiving of a complete data packet), you can specify to run a status check, or to return the status in the parameter block of the call source. The status of RmIO calls for write operations is checked at the start and end of the calls. 5.8.1.2 Timeout handling You can avoid system deadlocks by setting a time monitor for I/O requests. A timeout is valid for read and write requests (same read and write time interval, independent of the length of information to transmit). This type of timeout handling is enforced whenever the unit is reserved for a task. Specify the selected time interval in the reservation request. A timeout is restricted to write jobs; the time interval is calculated based on the buffer size and a timeout value per character. This type of timeout is used if UCD.TIMOUT 0 during software compilation and the first type of timeout was not selected for unit reservation by setting a timeout value. Note that only the net length of the buffer is used to calculate the timeout value, whereas the start, completion, BCC, or DLE characters are ignored. 5.8.1.3 Transfer protocol Definitions The buffer or buffer content is always defined in the following by the net information of an I/O job, that is, the information that an RMOS3 task transmits or receives. The term data block always denotes the data quantity that is actually transmitted over the cable. It is assumed that transmission is handled in transparent mode, which means that any 8-bit information in the buffer can be transferred. Data transmission also includes control characters that do not belong to the user data. A special transmission protocol (3964 or 3964R) for transmission of the buffer contents is used for communication between computers. Function principle The COM driver accepts the data offered by a user task and exchanges this data with the link partner by means of asynchronous procedure. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 235 Functions and configuration of the basic I/O system 5.8 COM driver Data transmission procedure The 3964 or 3964R protocol is used for communication between the link partners. This data transmission procedure is a secure protocol for byte-oriented data exchange between the link partners. The data is transmitted in transparent, asynchronous half duplex mode, which means that no restrictions are applied in terms of ASCII code (as in 38XX protocols for example). 5.8.1.4 Signal sequences Different monitoring times are used to monitor data transmission. Acknowledgment monitoring time TQ The acknowledge monitoring time is started on completion of the transmission of the STX, ETB, ETX or BCC (for 3964R) control characters. The RmIO is aborted with corresponding message if no acknowledgment was received on completion of three transmissions. You can select an acknowledge monitoring time TQ of 2 s (with TZ = 200 ms) or 550 ms (with TZ = 100 ms) in UCD.PCMODE. Parameter UCD.TQ_VAL is provided for handling special situations and can be used to set any acknowledge monitoring time in units of 10 ms. Character monitoring time TZ Once the COM driver receives data, it monitors each incoming character by means of time constant TZ. If no character is received within the monitoring time, the driver transmits a negative acknowledgment (NAK). The RmIO is aborted with corresponding message on completion of three unsuccessful retries. You can select a character monitoring time TZ of 100 ms (with TQ = 550 ms) or 200 ms (with TQ = 2 s) in UCD.PCMODE. Parameter UCD.TZ_VAL is provided for handling special situations and can be used to set any character monitoring time in units of 10 ms. Retry counter If no or a negative acknowledgment is returned for the data transmitted, this transmission is initiated two more times. The RmIO is aborted with corresponding message on completion of three unsuccessful retries. Initiation conflict Since both stations have equal rights, initiation conflicts must be expected if both partners simultaneously start a request to send. This conflict can be resolved at the condition that the one station (master) is assigned a higher priority, while the partner (slave) is assigned a lower priority. These priorities are declared in the UCD block (UCD.PCMODE) during configuration. Depending on the further configuration, the RMOS3 COM slave driver is now capable of reacting to initiation conflicts by setting one of two possible operating modes: RMOS3 V3.50 Reference Manual Part II 236 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver Mode 1 The COM driver can redirect operations to a different read job (see chapter "Example of signal sequences (Page 238)"). The following configuration has the effect that the COM driver suspends the current write job (Write-Hold, in BLOCKED mode) and activates a successive read job instead: BIT 0 (PRI) = 0 (configuration as slave; in UCD.PCMODE) BIT 3 (TQE) = 0 (acknowledge monitoring activated; in UCD.PCMODE) BIT 5 (TRE) = 0 (receive monitoring activated; in UCD.PCMODE) Activation of acknowledge and receive monitoring; which means that: timer (additional interrupt) in operation, mask is open (PIC), and the time monitoring routine points to entry point address X_3964_TIME_INTR Note Once the STX control character that generates the initiation conflict was received, the slave side is provided the time TQm/2 (m = master) to resolve the conflict by activating a queued read job. The ready to receive state on slave side (send DLE) can now be communicated to the master side within the time interval TQm. The figure "Master-slave configuration with initiation conflict (Page 240)" describes the signal sequences and further details. Mode 2 The COM driver cannot redirect operations to a successive read job (3964 standard). Bit 5 = 1 in UCD.PCMODE, which means that receive monitoring is deactivated. The driver configured as slave is therefore prevented from redirecting to a successive read job and the write job on slave side is aborted with indication (-10) in the primary status byte. Data backup Each character to transmit is appended a parity bit to protect the data against transmission errors. Select even or odd parity in corresponding initialization data of the I/O block. Even parity is the usual setting. In your configuration, you can also define a BCC (Block Check Character) parameter UCD.PCMODE. With BCC= 3964R protocol Without BCC= 3964 protocol RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 237 Functions and configuration of the basic I/O system 5.8 COM driver This BCC is derived from the total of the bits of equal value in all characters of a block. The check character is supplemented with an additional bit to form even parity. The BCC generated in this way is itself backed up after the character parity procedure is completed and is then transferred at the end of the block. All block characters except the STX control character are used. The BCC can be used to check for loss of characters in the transmission process. General notes The application must transfer a read job to the driver no later than TQ/2, so that the ready-toreceive signal can be output by means of DLE within the time interval TQ after receipt of STX. 5.8.1.5 Example of signal sequences Figure 5-13 Receiving data Only with 3964R protocol. BCC is omitted in the 3964 protocol and TQ begins after ETX (ETB). 1) RMOS3 V3.50 Reference Manual Part II 238 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver Figure 5-14 Sending data Only with 3964R protocol. BCC is omitted in the 3964 protocol and TQ begins after ETX (ETB). 1) RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 239 Functions and configuration of the basic I/O system 5.8 COM driver Figure 5-15 Master slave configuration with initiation conflict The initiation conflict shown in this example is generated as follows: A send job from the slave to the master is to be executed (write start). The slave signals its read-to-send state to the master by transmitting STX. The slave now expects to receive control character DLE within the time TQs to signal the read-to-receive state of the master (see above, example in the "Transmitting data" figure). However, instead of returning DLE, the master also signals its read-to-send state by means of STX (initiation conflict; bold arrow). The slave now responds by setting the write job to the BLOCKED state (write hold) and starts the queued read job (read start). A DLE (bold arrow) signals the ready-to-receive state of the slave within the time interval TQm. The data is then transmitted from the master to the slave. RMOS3 V3.50 Reference Manual Part II 240 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver On completion of the read job, the slave restarts and executes the suspended write job. 5.8.1.6 Control characters The following table describes the control characters of the COM driver, including the corresponding ISO 7-bit coding, as well as their meaning: 5.8.1.7 Control characters Coding (hex) Meaning STX 02 Transmission of STX signals the ready-to-send state to the communication partner. A response is expected within the acknowledgment monitoring time. DLE ETB 10 17 An ETB signals the end of a transmission block, but is followed by at least one more block. The block length is configured in UCD.BLKLEN (IOC64M36.ASM). DLE ETX 10 03 An ETX signals the end of transmission. DLE 10 DLE signals the ready-to-receive state after STX was received. DLE is the positive response to a successfully received transmission block. DLE also initiates the end character ETB or ETX. If DLE appears in the data block by chance, the COM driver adds a second DLE (doubling) to notify the recipient of this peculiarity. The receiving DUST hides the additional DLE again. NAK 15 NAK is the negative response to a corrupted block received. Opcodes of the COM driver The COM driver executes the following opcodes. 00H Reserve unit (C64_RESERVE) 01H Release unit (C64_RELEASE) 02H Read (C64_READ) 03H Write (C64_WRITE) 04H Redefine and initialize the unit (C64_CREATE_NEW) On detection of an invalid opcode, the driver stops execution of the I/O request and returns an error code (-1) in the primary status byte. For more information on the handling of opcodes, refer to the next chapters. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 241 Functions and configuration of the basic I/O system 5.8 COM driver 5.8.2 RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: 5.8.2.1 Function, bit 3..0 pState Function code of the selected driver function pParam Points to a data block with other function-specific parameters. Status pointer that reports internal states of the driver. Function parameter This parameter sets the selected COM driver functions (bits 0 to 3) and controls the sequence of the driver function. Bit Values 7 Function Preemptive bit 0 Sort I/O request based on 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..04H Valid opcode 05H..0FH reserved Opcode (bits 0 to 3) The COM driver executes the following opcodes, depending on the configured unit type (see UCD.TYPE). 00H Reserve unit (C64_RESERVE) 01H Release unit (C64_RELEASE) 02H Read (C64_READ) 03H Write (C64_WRITE) 04H Redefine and initialize the unit (C64_CREATE_NEW) On detection of an invalid function code, the COM 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. RMOS3 V3.50 Reference Manual Part II 242 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver 5.8.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 COM 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. 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 C64: BAD STS USRT-8251. 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 reserved/not reserved. -3 1 2 0000 0000H I/O request terminated due to timeout 0000 0000H reserved -4 -5 0000 0000H reserved -6 1 2 0000 0000H I/O request terminated by External Change Interrupt at the SCC 8530 block 3 -7 1 2 0000 0000H I/O request terminated by Special Receive Interrupt at the SCC 8530 block 4 -8 00H 0000H 0000 0000H 0000 0000H mismatch of the BBC character and the calculated value RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 243 Functions and configuration of the basic I/O system 5.8 COM driver 5.8.2.3 Primary status byte Secondary status byte 2nd status word 3rd and 4th status word Meaning -9 00H 0000H 0000 0000H Receive buffer overflow -10 00H 0000H 0000 0000H Initiation conflict -11 1 2 0000 0000H Protocol error: Received invalid control character -12 1 2 0000 0000H TQ time error -13 1 2 0000 0000H TZ time error 1 The last byte read or transferred is entered, depending on the I/O request. 2 Number of actually transferred bytes. 3 The External Change Interrupt is triggered by a Transmit Underrun Condition, or by a zero setting in the baud rate generator. 4 The Special Receive Interrupt is triggered on detection of a parity error in data transmission with parity check. 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 COM driver function (e.g. read). It is sufficient to set a parameter block length of 20 bytes if verification of the status feedback is omitted. For more information about the parameter block bytes, refer to the description of the COM driver functions. Always set reserved parameters to zero. Type Offset Description Note POINTER far 0 Offset/segment of the output buffer 1 WORD int 6 Length of the output buffer 2 POINTER far 10 Offset/segment of the input buffer 1 WORD int 16 Length of the input buffer 2 WORD int 20 Controller status information 3 24 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 overshoot (FFFFH..0H). 2 Only the two least significant bytes are used. The maximum I/O length amounts to 64 KB. 3 Reserved for the transfer of block-related status information on completion of an I/O operation (UCD.STMODE). The least significant byte contains the status information read for the status check. At I/O block 8530, the most significant byte is loaded with the content of RR0 and the least significant byte contains RR1. RMOS3 V3.50 Reference Manual Part II 244 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver 5.8.3 Opcodes 5.8.3.1 Reserve unit (C64_RESERVE) Opcode: Parameter block: 00H C64_RESERVE 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. 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. Parameter block for reservation requests: Type Offset Description POINTER far 0 reserved WORD int 6 reserved POINTER far 10 reserved WORD int 16 Timeout value (multiple of 256 ms) WORD int 20 reserved Note 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 ms) 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 output and can only be deactivated again by means of a corresponding release operation (reservation with timeout value 0). 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. The reservation is also revoked if the unit was reserved by the same task in order to prevent system deadlocks. In this case, a subsequent release request of the task is completed with error code (-2) in the primary status byte. The value 0 in the timeout parameter set at the time of reservation suppresses only the time monitoring function for input requests. You must also set UCD.TIMOUT to zero to globally discard time monitoring. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 245 Functions and configuration of the basic I/O system 5.8 COM driver 5.8.3.2 Release unit (C64_RELEASE) Opcode: Parameter block: 01H None C64_RELEASE 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. 5.8.3.3 Read (C64_READ) Opcode: Parameter block: 02H 24 bytes C64_READ This function transfers characters from an I/O device to a user-defined input buffer. 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 (without control characters STX, DLE, BCC, and NAK). With zero user buffer length, the input request is terminated without having been processed and without error message (no status information). If desired, the COM driver enters block-specific status information on completion of the RmIO call. This status information can be used, for example, to detect parity errors. The echo function is always disabled when receiving characters. The read operation is terminated based on the following criteria: When a terminator has been received. On reaching the maximum buffer length. In this case, further entries will be rejected. The I/O job is completed with status -9. If still receiving corrupted blocks after three retries. The I/O job is completed with status -8. Monitoring times are (TQ or TZ) are exceeded. The I/O job is completed with status -12 and -13 for TQ or TZ. Detection of invalid control characters. The I/O job is completed with status -11. Timeout The I/O job is completed with status -3. RMOS3 V3.50 Reference Manual Part II 246 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver Parameter block for read request: 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 WORD int 20 Controller status information 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. 5.8.3.4 Write (C64_WRITE) Opcode: Parameter block: 03H 24 bytes C64_WRITE 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 write. With zero output buffer length, the write request is terminated without having been processed and without error message (no status information). Th status check or status feedback of the I/O block is initiated at the start and completion of a write job. On timeout, the status prior to the start is returned for a write job, while the value 0 is returned for the read operation. Parameter block for write request: 5.8.3.5 Type Offset Description POINTER far 0 Address of the output buffer Note WORD int 6 Length of the output buffer POINTER far 10 reserved WORD int 16 reserved WORD int 20 Controller status information Redefine unit (C64_CREATE_NEW) Opcode: Parameter block: 0CH 20 bytes C64_CREATE_NEW 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. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 247 Functions and configuration of the basic I/O system 5.8 COM driver Parameter block for re-initialization: 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 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 19 words are fetched from the UCB parameters, while the remaining words are taken from the corresponding UCD parameters. The program first executes the read request if a simultaneous re-initialization request is pending. 5.8.4 Configuration 5.8.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 COM driver, you can use the C function RcInit3964() 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 SHR Identification of shared controllers (0FFH if char none) 0FFH INIT Entry point of the initialization routine in the driver void NEAR * X_3964_INIT SVC RIO-SVC entry point for driver void NEAR * X_3964_SVC FLAGS Driver flags: char 01H Bit0=1: Parallel driver Bit1=1: Type II driver Bit2=0: Initialization in the boot sequence 1 FMAX Maximum function code for type II driver char 00H RESERV 2 reserved bytes char 00H, 00H This value is occupied during the system configuration. RMOS3 V3.50 Reference Manual Part II 248 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver 5.8.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 more information about the initialization settings for the general part of the UCD block, refer to the System Manual, chapter "Unit Control Data table (UCD)". 1 5.8.4.3 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 handler routine (assigned internally) UNS 8 short Task ID of the task started after an unexpected input PORT 10 short Driver-specific data (120/246 bytes) 256 Total 1 See interrupt routines of the BYT driver. 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 UCMODE 10 short Unit Control Code PRTSEG 12 short USART segment PRTDAT 14 int USART data port PRTCMD 18 int USART command port PORT_2 22 int USART extra port 2 PORT_3 26 int USART extra port 3 PRTSTA 30 int USART status port STMODE 34 short Status Control Mask STARET 36 short Error Reset byte and retry factor for USART status check FREE_0 38 short reserved TIMOUT 40 short Timeout value/character RECOVR 42 short I/O delay time FREE_1 44 short reserved BLKLEN 46 short Block length PCMODE 48 short Protocol mode TQ_VAL 50 short TQ monitoring time TZ_VAL 52 short TZ monitoring time FREE_4 54 short reserved FREE_5 56 short reserved ICOUNT 58 short Number of init outputs MOBYTE 60 short 1st init output ..... ... MOBYTE 254 short nth init output Note RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 249 Functions and configuration of the basic I/O system 5.8 COM driver UCMODE (Unit Control Code) Bit Designatio n Meaning 15 x reserved 14 x reserved 13 x reserved 12 x reserved 11 UC 10 UC 9 UC 8 UC USART ID: 0000 = USART 8251A 0100 = SCC 8530 1001 = UART 8250 all others are reserved 7 x reserved 6 x reserved 5 x 4 SW 3 SR 2 ST 1 CT 0 MD USART status enable: 00 = no verification, no status enable, ID for USART status is ignored. 01 = status enable for read request 10 = status enable for write requests 11 = status enable for read and write requests 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 ID for DIO or MMIO 0 = DIO 1 = MMIO 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 250)") (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. RMOS3 V3.50 Reference Manual Part II 250 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver 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 250)") (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 250)") (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. 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 (configurable)1) CMD A/B (configurable)1) - CMD A CMD B 8251 DATA CMD - - STS 8250 DATA MODEM CTRL LINE CTRL INTR ENABLE LINE STS The "configurable" add-on means that the port addresses of channel A or B must be used, depending on the configured device. 1) STMODE (Status Control Mask) If a status check (CT = 1, SW/SR <> 00) was selected in the Unit Control Code (UCMODE) , the COM 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 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 251 Functions and configuration of the basic I/O system 5.8 COM driver The COM 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 status information read mismatches the value of the comparison mask. The COM 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. 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. 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 COM 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. RECOVR (recovery time) The COM 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 I/O block. The delay value depends on the processor used and on its clock frequency. BLKLEN The value at parameter BLKLEN defines the block length to be used. No blocks are formed if the value is zero. RMOS3 V3.50 Reference Manual Part II 252 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver PCMODE (protocol mode) Bit Designation Meaning 15 x reserved 14 x 13 x 12 x 11 x 10 x 9 x 8 RBC Character length 0 = 8 bits per character 1 = 7 bits per character 7 x Reserved 6 x 5 TRE Receive monitoring (TRE) 0 = activated 1 = deactivated 4 TZE Character monitoring (TZ) 0 = activated 1 = deactivated 3 TQE Acknowledgment monitoring (TQ) 0 = activated 1 = deactivated 2 UB Monitoring times; handshake with link partner 0 = TQ = 2 s, TZ = 200 ms 1 = TQ = 550 ms, TZ = 100 ms 1 BCC BCC mode 0 = BCC is not generated 1 = BCC is generated 0 PRI Priority for initiation conflict: 0 = slave 1 = master Definition of receive monitoring: If no receive job is pending and STX is received, this status is retained for the duration of TQ/2 before the successive receive job is processed. TQ_VAL The value at this parameter (handshake with link partner) defines the acknowledge monitoring time to use in 10 ms units. A zero value defines the default 2000 ms or 550 ms (see parameter PCMODE). TZ_VAL The value at this parameter (handshake with link partner) defines the character monitoring time to use in 10 ms units. A zero value defines the default 200 ms or 100 ms (see parameter PCMODE). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 253 Functions and configuration of the basic I/O system 5.8 COM driver ICOUNT This value defines the number of init units (MOBYTE). The system provides up to 40 init units. If the value at parameter ICOUNT is higher, the program initializes a maximum of 40 units. MOBYTE (init output) This value corresponds to an init unit and is interpreted by the COM driver as follows: Least significant byte Init byte or mode byte to be output. Most significant byte Bits 8 to 13 The meaning of these bits depends on bit 15: offset for PRTDAT, or output port ID with the following meaning: Identifier 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 Bit 14 Bit 15 0 Value is output. 1 Value is read (certain controllers are initialized by reading registers). 0 Bits 8 to 13 are interpreted as ID. 1 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. 5.8.4.4 Interrupt routines of the COM driver The BYT driver provides 6 entry point addresses for its interrupt handler routines that are declared as PUBLIC symbols with the following meaning: X_3964_RCVR_INTR: Interrupt handler routine for input units (receiver for I/O devices) (e.g. 8251). X_3964_TMTR_INTR: Interrupt handler routine for output units (transmitter for I/O devices) (e.g. 8251). RMOS3 V3.50 Reference Manual Part II 254 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.8 COM driver X_3964_COM_INTR: Entry point address for controllers (I/O devices) with shared interrupt for all actions (e.g. 8530, 8250). X_3964_TIME_INTR: Entry point address for the time monitoring routine. This routine is required only once for the first device unit. It is independent of the number of device units. The timer interrupt must be set to 10 ms. X_3964_SPEC_INTR: Entry point address for Special Receive Interrupt (8530) X_3964_EXST_INTR: Entry point address for External Status Interrupt (8530). Note If both channels at SCC 8530 are used for units that are assigned to different drivers, you must use the special interrupt handler in SWICOM.ASM. Verify that the interrupt with the lower vector number (higher priority) is assigned to the receiver. 5.8.4.5 Stack requirements of the COM driver S state 42 words I state 54 words DI state 0 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 255 Functions and configuration of the basic I/O system 5.9 SRAM driver 5.9 SRAM driver 5.9.1 Areas of application Emulation of a logical volume R0: The SRAM driver can be used to emulate an SRAM disk for battery-backed SRAM. The driver is registered in the RMOS3 file system in order to manage SRAM as logical volume (volume R0:). If not already formatted, the driver automatically formats the SRAM disk at startup. Addressing by means of memory hole The SRAM driver is addressed using a memory hole that can be configured in the CPU. If the memory hole is not activated, the following message is output at RMOS3 startup: NUC: Memory hole disabled in BIOS Setup NUC: SRAM driver not loaded 5.9.1.1 Organization of tasks/functions The driver is not interrupt-driven and merely represents the SVC section of a driver. It is realized as driver to enable its registration with the HSFS and to enable addressing of the SRAM disk as logical volume. RMOS3 V3.50 Reference Manual Part II 256 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.9 SRAM driver Overview: Figure 5-16 Structure of the RMOS3 driver functions The logical management of the memory as volume is handled by the HSFS. The HSFS also handles the formatting. 5.9.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 pState Function code of the selected driver function pParam Points to a data block with other function-specific parameters. Status pointer that reports internal states of the driver. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 257 Functions and configuration of the basic I/O system 5.9 SRAM driver 5.9.2.1 Function parameter This parameter sets the selected SRAM driver functions (bits 0 to 3) and controls the sequence of the driver function. Bit Values 7 Function Preemptive bit 0 Sort I/O request based on 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..04H Valid opcode 05H..0FH reserved Opcode Opcode define Meaning 00H RD40_RESERVE Reserve unit 01H RD40_FREE Release unit 02H RD40_READ_ONE Read logical block 03H RD40_WRITE_ONE Write logical block 04H RD40_FORMAT Format (dummy function) 05H RD40_READ_MORE Read logical blocks 06H RD40_WRITE_MORE Write logical blocks 07H reserved 08H reserved 09H reserved 0AH reserved 0BH reserved 0CH reserved 0DH 0EH 0FH reserved RD40_IOCTRL I/O control function reserved On detection of an invalid function code, the driver stops execution of the I/O request and returns an error code (-1) in the primary status byte. The RD40_IOCTRL function splits itself into sub-operations. These are adapted to suit SRAM driver requirements. RMOS3 V3.50 Reference Manual Part II 258 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.9 SRAM driver Sub-operation define Meaning 00H RD40_GET_PARAM Read operating parameters 01H reserved 02H 5.9.2.2 RD40_IDENT Calculate the partition size. This merely returns the parameter size from the UCD, converted in to bytes. Parameter pState At the RmIO system call, parameter pState is used to pass a pointer to a structure of the type RmIOStatusStruct. 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 saved by the nucleus, which cannot be used to derive the status after the RmIO system call was processed. For several quasi-parallel RmIO system calls (bit 6 in parameter Function), each call must provide a separate status field for returning the parameters. The first byte in the status field represents the primary status byte and the second the secondary status byte. The next bytes are assigned to word groups and designated as 2nd status word (in RMOS2) or 3rd and 4th status word (in RMOS3). 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 RD40 driver. Primary status byte Secondary status byte 2nd status word 3rd and 4th status word Meaning 0 00H 0000H 0000H I/O request is queued. 1 00H 0000H 2 00H 0000H 0000H 0000H Busy processing the I/O request. 0000H 0000H I/O request successfully completed. 0000H -1 00H 0000H 0000H 0000H -2 00H 0000H 0000H 0000H -3 -4 00H 00H 0000H 0000H 0000H I/O request rejected due to invalid parameterization Reserve/release operation was not executed, because the unit is already/not reserved 0000H Missing partition. Parameter size or addr in the UCD is 0. 0000H reserved 0000H -5 00H 0000H 0000H 0000H Write error. A write error was detected. The driver verifies successful completion of write operations by means of readback and comparison (verify). RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 259 Functions and configuration of the basic I/O system 5.9 SRAM driver Table 5- 10 5.9.2.3 Defines for status displays Value Define 0 RD40_STS_QUEUE 1 RD40_STS_BUSY 2 RD40_STS_SUCCESS -1 RD40_STS_ WRONG_PARAM -2 RD40_STS_BAD_RSVR -3 RD40_STS_PART_NOT_EXIST -4 reserved -5 RD40_STS_READ_WRITE_ERROR 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 SRAM driver function. The respective meaning of the bytes of the parameter block is explained in the description of SRAM driver functions. Always set the reserved parameters in the parameter block to zero. 5.9.3 Opcodes 5.9.3.1 Reserve unit (RD40_RESERVE) Opcode: Parameter block: 00H not required RD40_RESERVE This function reserves the unit specified in the RmIO system call exclusively for RmIOs of the calling task. RmIOs of other tasks are accepted, but not executed until the unit has been released. RmIOs 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. 5.9.3.2 Release unit (RD40_FREE) Opcode: Parameter block: 01H not required RD40_FREE This function revokes the reservation of the unit specified in RmIO system call. 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. RMOS3 V3.50 Reference Manual Part II 260 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.9 SRAM driver 5.9.3.3 Read logical block (RD40_READ_ONE) Opcode: Parameter block: 02H 12 bytes RD40_READ_ONE This operation transfers a logical block (512 bytes) to a read buffer. The logical block is read starting at the logical block address specified in the parameter block. Type Offset Description Parameters ulong 0 Logical block address lba void _FAR * 4 Read buffer address buf_adr ushort 10 reserved reserve An incorrect logical block address aborts the operation with error code (-1) in the primary status byte. If no SRAM exists, the operation is aborted with error code -5 in the primary status byte. Type definition: RD40_READ_ONE_TYP 5.9.3.4 Write logical block (RD40_WRITE_ONE) Opcode: Parameter block: 03H 12 bytes RD40_WRITE_ONE This operation transfers a logical block (512 bytes) from a write buffer to a unit. The logical block is written starting at the logical block address specified in the parameter block. Type Offset Description Parameters ulong 0 Logical block address lba void _FAR * 4 Write buffer address buf_adr ushort 10 reserved reserve The write buffer contains the data to transfer. An incorrect logical block address aborts the operation with error code (-1) in the primary status byte. Type definition: RD40_WRITE_ONE_TYP 5.9.3.5 Format (RD40_FORMAT) Opcode: Parameter block: 04H not required RD40_FORMAT This operation has no effect and is only implemented for reasons of RMOS3 compatibility. Unformatted SRAM is formatted automatically with function x_rd40_init() when you integrate the driver in the HSFS. Function x_rd40_init() is therefore called at startup. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 261 Functions and configuration of the basic I/O system 5.9 SRAM driver 5.9.3.6 Read logical blocks (RD40_READ_MORE) Opcode: Parameter block: 05H 12 bytes RD40_READ_MORE This operation transfers one or several logical blocks (512 bytes) from a unit to a read buffer. The logical blocks are read starting at the logical block address specified in the parameter block. Type Offset Description Parameters ulong 0 Logical block address lba void _FAR * 4 Read buffer address buf_adr ushort 10 Number of blocks num_blk An incorrect logical block address aborts the operation with error code (-1) in the primary status byte. If no SRAM exists, the operation is aborted with error code -5 in the primary status byte. Type definition: RD40_READ_MORE_TYP 5.9.3.7 Write logical blocks (RD40_WRITE_MORE) Opcode: Parameter block: 06H 12 bytes RD40_WRITE_MORE This operation transfers one or several logical blocks (512 bytes) from a write buffer to a unit. The logical blocks are written starting at the logical block address specified in the parameter block. Type Offset Description Parameters ulong 0 Logical block address lba void _FAR * 4 Write buffer address buf_adr ushort 10 Number of blocks num_blk The write buffer contains the data to transfer. An incorrect logical block address aborts the operation with error code (-1) in the primary status byte. Type definition: RD40_WRITE_MORE_TYP 5.9.3.8 I/O control operation (RD40_IOCTRL) Opcode: Parameter block: 0EH 12 bytes RD40_IOCTRL Parameter block: Type Offset Description Parameters ushort 0 Sub-operation sub_fct ushort 2 Sub-operation-specific allocation byte_num void _FAR * 4 Sub-operation-specific allocation buf_adr ushort 10 reserved reserve RMOS3 V3.50 Reference Manual Part II 262 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.9 SRAM driver Sub-operation: Sub-operation Meaning 0x00 Read operating parameters 0x01 reserved 0x02 Get partition size (from UCD). Type definition: RD40_IOCTRL_TYP Read operating parameters Sub-operation: 00H This sub-operation reads the current operating parameters of a unit assigned to the RMOS3 driver. The parameters are saved to a buffer. The buffer address is transferred in the parameter block. Parameter block: Type Offset Description Parameters ushort 0 Sub-operation (00H) sub_fct ushort 2 reserved byte_num RD40_IO_GET_P ARAM FAR * 4 Address of the input buffer buf_adr ushort 10 reserved reserve Type definition for RD40_IO_GET_PARAM: typedef struct RD40_IO_GET_PARAM_S { ushort unit_cnt; UCD_RD40_COMMON ucd_com; UCD_RD40_TYPE ucd_type; UCB_RD40_TYPE ucb_type; } RD40_IO_GET_PARAM; Type definition for UCB_RD40_TYPE: typedef struct { ulong uchar _FAR uchar _FAR ulong ulong uchar } UCB_MC2OS_TYPE; part_length; *disk_start_adr; *buf_adr; act_adr; end_adr; (*rw_funct)(); Structure of UCB_RD40_TYPE: Parameters Description Type part_length Length in bytes of the memory range managed by the driver. Calculated based on the size parameter of the UCD (size*1024). ulong disk_start_adr Pointer to the start of the memory range. This pointer was requested by RMOS3 and is valid for part_length. uchar _FAR * buf_adr Buffer address of an active RmIO call uchar _FAR * Current disk read/write address ulong end_adr End address of a read/write function. ulong rw_funct Pointer to the current RmIO read/write function. (nearPointer) char * act_adr RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 263 Functions and configuration of the basic I/O system 5.9 SRAM driver Calculating the partition size Sub-operation: 02H Parameter block: Type Offset Description Parameters ushort 0 Sub-operation (02H) sub_fct ushort 2 reserved reserved ulong * 4 Address of the input buffer part_length ushort 10 reserved reserve At the call, a pointer is passed in the parameter block to a 32-bit word that returns the partition size that is parameterized in the driver. The value is derived from the size (size*1024) parameterized in the UCD. You can use this value, for example, to format the disk. 5.9.4 Configuration The driver (device) and its units (units) are configured by means of tables. DCD (Device Control Data) UCDs (Unit Control Data) You need these tables to implement the driver in RMOS3. The following describes the structure of the tables. 5.9.4.1 Driver control data (DCD) table The DCD (Device Control Data) defines driver-specific configurations. Parameters Description Type Standard value ucd Address of the first UCD structure for this driver near pointer to 1) units Number of units for this driver uchar 1) shr ID of a different DCD that also uses this control (FFh if none) uchar 0xFF 1) init Entry point of the initialization routine rmproc 2) svc RIO-SVC entry point for this driver rmproc 3) flags Driver flags uchar 0x03 RmUCDStruct Bit 0=1 parallel driver Bit 1=1: Type II driver Bit 2=0: Initialization in the boot sequence fmax Maximum opcode for type II driver uchar 0xF reserv 2 reserved bytes uchar 0x00 1) This value is occupied by RMOS3 2) X_RD40_INI_UCB for the RMOS3 driver 3) X_RD40_SVC_BR for the RMOS3 driver The DCD block is created in the RCCPUIMC.C file. RMOS3 V3.50 Reference Manual Part II 264 Programming Manual, 07/2012, A5E03692298-01 Functions and configuration of the basic I/O system 5.9 SRAM driver 5.9.4.2 Unit Control Data (UCD) table Type definition for UCD typedef struct UCD_RD40_S{ UCD_HEAD head; UCD_RD40_TYPE type; UCD_RD40_COMMON com; } UCD_RD40; The UCDs are created in the RCCPUIMC.C file. The driver-specific parameters are available as of port in the UCD block. The following parameters must be specified for unit 0: Table 5- 11 Parameters in UCD_HEAD Parameters Description Type Standard value pid ID of the process operating the unit. uchar 0 intno Interrupt number uchar 0 int_adr Address of the interrupt handling routine rmfarproc (void *)0 uns Task ID of the task started after an unexpected interrupt was triggered ushort -1 Table 5- 12 Parameters in UCD_RD40_TYPE Parameters Description Type start_adr Physical start address of the memory range. ulong size Drive storage space in KB. ushort The driver creates a descriptor based on start_adr and size. This descriptor is used internally in the driver to access memory. The default values specified in RCCPUIMC.H (RD40_RAM_ADR, RD40_RAM_SIZE) should be used for start_adr and size. Table 5- 13 Parameters Parameters in UCD_RD40_COMMON Description Type srb_border SRB threshold value uint srb_time Waiting time triggered on undershoot of the SRB threshold. uint srb_border RMOS3 driver operations are executed in sequential mode in RMOS3 S state. The time it takes to process extensive read/write operations poses the risk of overflow of the S state queue. Parameter srb_border specifies the number of SRBs that must remain available in the RMOS3 queue to complete the processing of a write/read operation. If the amount falls short of this threshold, the RMOS3 driver interrupts processing of the read/write operation for the duration of the srb_time waiting time and then checks the system again for availability of a sufficient number of SRBs. Processing is resumed only if the result is positive. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 265 Functions and configuration of the basic I/O system 5.9 SRAM driver If srb_border is set to 0, the RMOS3 driver calculates the threshold at system startup. The SRB threshold is calculated as follows: SRB threshold = X_SRB_NUM - X_VECTORS_NUM X_SRB_NUM Number of SRBs specified in the software configuration. X_VECTORS_NUM The assembler calculates this parameter when compiling the RMOS3 software configuration; results can be viewed in the listing. The result represents the total of all hardware and software interrupts. If a value unequal 0 is entered for srb_border, this value will be used directly as threshold. srb_time At this parameter, you specify the time in milliseconds that the RMOS3 driver will interrupt a read/write operation when the number of SRBs falls below the SRB threshold. If the value 0 is set at UCD_SRB_TIME, the RMOS3 driver calculates its suspend time as follows at system startup: srb_time = 2 x (X_SRB_NUM - SRB threshold value) A value unequal 0 in UCD_SRB_TIME is used directly as waiting time. RMOS3 V3.50 Reference Manual Part II 266 Programming Manual, 07/2012, A5E03692298-01 Abbreviations/glossary A API Application Programming Interface BIOS Basic Input/Output System BPB BreakPoint Block BSP Board Support Package. CLI Command Line Interpreter; user interface to the operating system. Client Consumer or customer of a service, sometimes also used to denote a relation of two cooperative processes in which the client assumes the active role. Configuration space Each module on the PCI bus must provide a block of 64 dwords for its configuration. The first 16 dwords are defined in the PCI specification. CRUN ANSI C runtime library for RMOS3. Provides all C functions in accordance with the ANSI Draft Standard ISO/IEC DIS 9899 (published 1990) in the RMOS3 multitasking environment. DCB Driver Control Block; table of current dynamic data of the driver. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 267 Abbreviations/glossary DCD Driver Control Data; table of the default configuration data. Device Driver program; RMOS3 handles I/O operations by means of special programs, namely driver programs (in short drivers) and their subunits (units). The specific drivers to be made available to the operating system is specified in the system configuration. The operating system identifies the drivers based on their number, namely the device ID. DMA Direct Memory Addressing Driver Program module in the operating system for handling the operation or control of I/O blocks DWB Directory Wait Block EIDE Enhanced Integrated Drive Electronics EOI End Of Interrupt EPROM Erasable Programmable Read Only Memory; semiconductor memory chip that can be programmed by users EEPROM Electrically Erasable EPROM (fixed value memory) EWB Event Flag Wait Block; management block for the waiting for an event flag FTP File Transfer Protocol RMOS3 V3.50 Reference Manual Part II 268 Programming Manual, 07/2012, A5E03692298-01 Abbreviations/glossary GDT Global Descriptor Table Heap Memory pool HLL High Level Language-Debugger HSFS High Speed File System IDT Interrupt Descriptor Table IRB I/O Request Block to a driver Job Programs and commands started at the RMOS3 CLI (Command Line Interpreter). LAN Local Area Network LBA Logical Block Addressing Message A message is interpreted in RMOS3 as the content of a 3-word buffer MMB Mailed Message Block; management block for waiting to fetch a message. MPIC Master Programmable Interrupt Controller RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 269 Abbreviations/glossary NMI Non-Maskable Interrupt NPX Numeric Processor Extension; numerical co-processor PCI Peripheral Component Interconnect; bus system with 32-bit data bus PCMCIA Personal Computer Memory Card International-Association PCMPIC PC Master Programmable Interrupt Controller PCSSPIC PC Soft Slave Programmable Interrupt Controller PIC Programmable Interrupt Controller PIT Programmable Interrupt Timer block Placeholder character Also known as wildcard or joker character. Special omission characters: "*" represents a group of letters or figures, "?" "?" represents a single alphanumerical character. PPP Point-to-Point Protocol (Internet) PWB Pool Wait Block; management block for waiting for memory allocation RMOS3 V3.50 Reference Manual Part II 270 Programming Manual, 07/2012, A5E03692298-01 Abbreviations/glossary Queue Queue RAM Random Access Memory RCB Restart Control Block; block for managing task start requests RMB Receive Message Block; management block for waiting for message. RMOS Real-time Multitasking Operating System Root directory Files are stored in HSFS in directories. Directories in HSFS form a hierarchic structure. The root directory is the top directory of a volume. Only one root directory is available per volume (partition). RTQ Ready Task Queue; internal structure of the nucleus for managing all tasks in READY state. SDB Supervisor Descriptor Block; used to pass parameters on system calls. Server Service-providing partner in the relationship between two cooperating processes SMP Siemens Microcomputer PCB system SMR System Memory Resource; system memory block that the nucleus creates for internal management. Generic term for TMB, SWB, RMB, RCB, PWB, MMB,IRB, EWB RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 271 Abbreviations/glossary SPIC Slave Programmable Interrupt Controller SRAM Shadow Random Access Memory SRB System Request Block; supervisor request block, structure for storing status transitions SSPIC Soft Slave Programmable Interrupt Controller Subdirectory On a data volume, all directories other than root are subdirectories. You must assign these subdirectories a name that is unique within the directory in which they were created. SVC Supervisor Call, system call SWB Semaphore Wait Block, data structure which the nucleus generates every time a semaphore must be waited for. TCB Task Control Block; table of current dynamic data for task control. TCD Task Control Data; table of default values, created for static tasks in the configuration and for dynamic tasks by the loader. TCP Transmission Control Protocol TCP/IP TCP Internet Protocol RMOS3 V3.50 Reference Manual Part II 272 Programming Manual, 07/2012, A5E03692298-01 Abbreviations/glossary Telnet Telecommunication Network; dialog service over TCP/IP networks TIB Timer Control Block TMB Time Monitor Block; created by the nucleus to manage time-related calls. UCB Unit Control Block; table of current dynamic data for controlling a unit UCD Unit Control Data; table of default configuration values Unit I/O device. Units are addressed by drivers. The units that can be addressed by a driver are specified in the driver configuration data. The operating system identifies units based on their number, namely the unit ID. RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 273 Abbreviations/glossary RMOS3 V3.50 Reference Manual Part II 274 Programming Manual, 07/2012, A5E03692298-01 Index A ABORT_INPUT, 129 ABORT_INPUT BYT driver, 99 ABORT_OUTPUT terminal mode, 100 API, 15 Application Programming Interface, 15 DMA_ID, 216 DMA_PAGE, 215 Driver functions, 37 Driver ID, 39 Drive-related parameters:, 211 Drive-specific data block, 209 Duplex mode BYT driver, 96, 98 E B Binary mode, 31 BOARD, 215 Buffer, 122 Buffer mode, 228 BYT driver, 96, 101, 104 BYT driver control characters, 99, 101 C C library function classes, 28 CANCEL, 26 Cancel bit, 114, 219 Carriage return character, 121 Centronics BYT driver, 96 Centronics CRT driver, 160 chdir, 28 CLI, 26, 81 Color attributes of the pages, 152 CONTROL, 213 COUNT_HL, 215 COUNT_ML, 215 COUNT_RL, 215 CRT drivers, 160 CRUN, 84 CRUN support, 26 Cursor control, 122 D Data types, 13 DCB, 39 Debugger, 87 Device ID, 39 Directory names, 29 Display page, 105 Echo mode, 97, 121 EGA functionality, 104 EGA functions, 97 Entry point address, 233 Error logger task, 84, 90, 147, 252 Event flag ID, 39 Exception handler, 80 Exception interrupt handler, 73 F FDC_BASE, 216 fdureopen, 31 FLAT memory model, 15 Floppy disk driver, 200 FORMAT, 214 Function, 40 G Graphic mode, 110 H Half duplex mode BYT driver, 96, 97 Half duplex mode CRT driver, 160 Hardware interrupt, 16 HD drivers, 218 History buffer, 122 History mode, 101 I Interrupt handler SVCs, 16 Interrupt routines of FD0, 216 IRB, 39 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 275 Index J S Jump table, 40 S state, 37 Secondary status byte, 125 Segmented memory model, 15 SELECT, 212 Semi-graphic characters, 110 SMR, 73 Software interrupt, 16 SRB, 73 SRBs, 147 STARET, 146, 147, 252 Status, 39 Status field, 115 STMODE, 146, 251 Subprograms, 39 SWCBYT.ASM, 121 SYSCON, 73 System processes, 37 System variables, 37 K Keyboard types, 96 L Line feed mode, 121 M Mailbox ID, 39 MAX_RETRY, 214 MAX_SEC_0, 214 MAX_SEC_N, 214 MAX_TRACK, 213 Memory model, 15 Memory pool ID, 216 MOBYTE, 151, 254 MODEXT, 154 Module-related parameters:, 211 N NMI (Non-Maskable Interrupt), 75 NUL file, 31 P Pages, 104, 106, 152 PARM_PTR, 222 Path names, 29 POOL_ID, 216 Preemptive bit, 118 Primary status byte, 118 Processor exceptions, 73 Program abortion, 26 PUBLIC symbols, 16 R release, 40 reserve, 40 reserved, 118 RINITBYT.C, 99, 154 RINITBYT.C, 100 RUBOUT, 171 T Task start, 150 Terminal control characters, 100 Terminal mode, 96 Text mode, 31 TIME_OUT, 215 Timeout, 17, 119, 120, 121 TIMOUT, 148 TIMOUT CRT driver, 160 Transformation table, 119, 149 Transparent mode, 96 TYPE, 212 Type I drivers, 39 Type II drivers, 39 U UCB, 39 UCD.UCMODE, 101 UCD.UNSCHR, 99 UCD_DMA_BASE, 215 UCD_STMODE, 118 UCD_TABBUF, 119 UCD_TIMOUT, 120 UCD_TOPCHR, 169 UCD_UCMODE, 114, 117, 119, 131 UCMODE, 145, 250 UCMODE (Unit Control Code), 144 UCMODE BYT driver, 111 Unexpected interrupts, 73 Unit, 104 UNSUNSCHR, 150 RMOS3 V3.50 Reference Manual Part II 276 Programming Manual, 07/2012, A5E03692298-01 Index W Window, 104, 152 Write page, 105 WRITE_TERMINATOR, 123, 167 X X_BYT_COM_INTR, 153 X_BYT_RCVR_INTR, 153 X_BYT_TMTR_INTR, 153 X_DM2_DRIVER, 199 X_FD0_INTR, 216 X_HD0_INTR, 233 XBLKLEN, 39 XBOX, 39 XDCB, 39 XDEVNUM, 39 XDEVUNIT, 39 XERRMSG, 39 XFLAGS, 39 XGENB, 39 XGEND, 39 XGENW, 39 XGRP, 39 XOFF BYT driver, 99 XOFF CRT driver, 161 XOFFSET, 39 XON BYT driver, 99 XON CRT driver, 161 XP1, 39 XP2, 39 XPOINTER, 39 XPOOLNUM, 39 XPRIS, 39 XPRIV, 39 XSEG, 39 XSEGLIM, 39 XSEQ, 39 XSTATUS, 39 XTASK, 39 XTNUM, 39 XTUNIT, 39 XUCB, 39 RMOS3 V3.50 Reference Manual Part II Programming Manual, 07/2012, A5E03692298-01 277 Index RMOS3 V3.50 Reference Manual Part II 278 Programming Manual, 07/2012, A5E03692298-01