RMOS3 V3.50 Reference Manual Part II RMOS3. RMOS3 real-time operating system RMOS3 V3.50 Reference Manual Part II. About this manual...

Transcription

1 About this manual... 1 Function groups 2 RMOS3 RMOS3 real-time operating system RMOS3 V3.50 Reference Manual Part II Programming Manual Data structures 3 Error codes and messages 4 Functions and configuration of the basic I/O system 5 A Abbreviations/glossary 07/2012 A5E

2 Legal information Warning notice system This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger. DANGER indicates that death or severe personal injury will result if proper precautions are not taken. WARNING indicates that death or severe personal injury may result if proper precautions are not taken. CAUTION indicates that minor personal injury can result if proper precautions are not taken. NOTICE indicates that property damage can result if proper precautions are not taken. If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage. Qualified Personnel The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems. Proper use of Siemens products Note the following: Trademarks WARNING Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed. All names identified by are registered trademarks of Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner. Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions. Siemens AG Industry Sector Postfach NÜRNBERG GERMANY A5E P 07/2012 Technical data subject to change Copyright Siemens AG All rights reserved

3 Table of contents 1 About this manual About this manual Notations Function groups RMOS3 functions Notes on programming in C Short description of the RMOS3 functions Configuration functions Miscellaneous functions CLI functions Startup code for C programs Problems when aborting a program Short description of the CLI functions C library functions Scope of the C library Short description of the C library functions Driver functions Application model Short description of the driver functions System variables for parameter transfer Differences between type I and type II drivers Data structures RmAbsTimeStruct RmAsciiTimeStruct RmDCDStruct RmEntryStruct RmIntrhandMailStruct RmIOStatusStruct RmIRBStruct RmMailboxStruct RmMailIDStruct RmMemPoolInfoStruct RmSpinLockStruct RmSysB RmTaskInfoStruct Programming Manual, 07/2012, A5E

4 Table of contents 3.14 RmTCDStruct RmTimeStruct RmTMBStruct RmUCDHeadStruct RmUCDStruct loader_result stdstruct Error codes and messages Nucleus Error codes of the RMOS3 API calls SVC exception handler CLI CRUN HSFS Debugger Resource reporter Task loader stl_load, stl_free LOADRM task loader Functions and configuration of the basic I/O system Overview BYT driver Properties Optional EGA functions Half/full duplex mode Control characters for BYT drivers and terminals History mode Data flow of received characters Special features for EGA units Opcodes of the BYT driver (bits 0..3) RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes of the BYT driver Reserve unit (BYT_RESERVE) Release unit (BYT_RELEASE) Read (BYT_READ) Write (BYT_WRITE) Unconditional writing (BYT_XWRT) Read character in transparent mode (BYT_ONE_XREAD) Write and read in transparent mode (BYT_WRT_XREAD) Write and read (BYT_WRT_READ) Programming Manual, 07/2012, A5E

5 Table of contents Skip line (BYT_SKIP_LINE) Clear screen (BYT_FORM_FEED) Read character to buffer in transparent mode (BYT_HSFS_XREAD) Write character (BYT_HSFS_WRT) Read interim buffer in transparent mode (BYT_POLL_XBUF) Check input buffer for abort characters (BYT_CHECK_ABO) Redefine and initialize the unit (BYT_CREATE_NEW) Multifunction (only for EGA units) Configuration Driver Control Data table (RmDCDStruct in RMTYPES.H) Unit Control Data table (RmUCDStruct in RMTYPES.H) Driver-specific parameters in the UCD block Interrupt routines of the BYT driver Configuring the control characters in Rinitbyt.c EGA specific configuration Ribtega.c Stack requirements of the BYT driver CRT drivers Properties Sequence of functions Timeout handling Control characters Opcodes of the CRT driver (bits 0 to 3) RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes of the CRT driver Reserve unit (CRT_RESERVE) Release unit (CRT_RELEASE) Read (CRT_READ) Write (CRT_WRITE) Write (CRT_WRITE) Read character in transparent mode (CRT_ONE_XREAD) Write and read in transparent mode (CRT_WRT_XREAD) Write and read (CRT_WRT_READ) Line feed/skip line (CRT_SKIP_LINE) Form feed/clear screen (CRT_FORM_FEED) Read character in transparent mode (CRT_HSFS_XREAD) Write character (CRT_HSFS_WRITE) Redefine unit (CRT_CREATE_NEW) Keyboard control characters for I/O devices ASCII codes used by the CRT DRIVER Configuration Driver control data table (DCD) Unit Control Data table (UCD) Driver-specific parameters in the UCD block Interrupt routines of the CRT2 driver Stack requirements of the CRT2 driver RAM disk driver Properties Programming Manual, 07/2012, A5E

6 Table of contents Sequence of the RmIO system call Opcodes of the RAM DISK driver RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes Reserve RAM DISK (00H) Release RAM DISK (01H) Read logical block (02H) Write logical block (03H) Dummy operation (04H) Read logical blocks (05H) Write logical blocks (06H) I/O control operation (0EH) Configuration Driver control data (DCD) table Unit Control Data table DMA driver Properties Functionality of the DMA driver Note for use as subprogram Special features of the DMA controller RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes Reserve unit (DMA_RESERVE) Release unit (DMA_RELEASE) Read from memory (DMA_READ) Write to memory (DMA_WRITE) Transmission abortion (DMA_ABORT) Redefine unit (DMA_CREATE) Subprogram calls of the DMA driver Program call (X_DM2_DRIVER) FD0 driver Properties Sequence of functions Opcodes of the FD0 driver RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes Reserve unit (FD2_RESERVE) Release unit (FD2_RELEASE) Read logical block (FD2_READ_1) Write logical block (FD2_WRITE_1) Format floppy disk (FD2_FORMAT) Read logical blocks (FD2_READ) Programming Manual, 07/2012, A5E

7 Table of contents Write logical blocks (FD2_WRITE) Position to track (FD2_SEEK) Position to track 0 (FD2_RECA) Get drive status (FD2_UNIT_RDY) Remove drive parameters (delete) (FD2_DELETE) Define drive parameters (create) (FD2_CREATE) Configuration Driver control data (DCD) table Unit Control Data (UCD) table Interrupt routines of the FD0 driver Stack requirements of the FD0 driver HD0 driver Properties Area of application and opcode RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes Reserve unit (00H) Release unit (01H) Read logical block (02H) Write logical block (03H) Format hard disk (04H) Read logical blocks (05H) Write logical blocks (06H) Read drive parameters (0AH) Remove drive parameters (delete or dismount) (0BH) Define drive parameters (create or mount) (0CH) Configuration Driver control data (DCD) table Unit Control Data (UCD) table Driver-specific parameters in the UCD block Interrupt routines of the HD0 driver Stack requirements of the HD0 driver COM driver Properties Sequence of functions Timeout handling Transfer protocol Signal sequences Example of signal sequences Control characters Opcodes of the COM driver RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes Reserve unit (C64_RESERVE) Release unit (C64_RELEASE) Programming Manual, 07/2012, A5E

8 Table of contents Read (C64_READ) Write (C64_WRITE) Redefine unit (C64_CREATE_NEW) Configuration Driver Control Data table (RmDCDStruct in RMTYPES.H) Unit Control Data table (RmUCDStruct in RMTYPES.H) Driver-specific parameters in the UCD block Interrupt routines of the COM driver Stack requirements of the COM driver SRAM driver Areas of application Organization of tasks/functions RmIO interface Function parameter Parameter pstate Parameter pparam Opcodes Reserve unit (RD40_RESERVE) Release unit (RD40_FREE) Read logical block (RD40_READ_ONE) Write logical block (RD40_WRITE_ONE) Format (RD40_FORMAT) Read logical blocks (RD40_READ_MORE) Write logical blocks (RD40_WRITE_MORE) I/O control operation (RD40_IOCTRL) Configuration Driver control data (DCD) table Unit Control Data (UCD) table A Abbreviations/glossary Index Programming Manual, 07/2012, A5E

9 Table of contents Tables Table 1-1 Commands Table 1-2 Abbreviations Table 1-3 General data types Table 1-4 Data types of the RMOS3 API Table 5-1 Combination of read and write operations in DUPLEX mode Table 5-2 Function code of the internal input interface Table 5-3 RmIO parameter Function of the BYT driver Table 5-4 Configuration as I/O device (e.g. terminal) Table 5-5 Configuration as output device (e.g. line printer) Table 5-6 Configuration as input device (e.g. keyboard): Table 5-7 RmIO parameter pstate Table 5-8 RmIO parameter pstate (continuation) Table 5-9 ASCII characters Table 5-10 Defines for status displays Table 5-11 Parameters in UCD_HEAD Table 5-12 Parameters in UCD_RD40_TYPE Table 5-13 Parameters in UCD_RD40_COMMON Programming Manual, 07/2012, A5E

10 Table of contents Figures Figure 2-1 System processes Figure 5-1 Data flow of an incoming expected character in the 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 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 Figure 5-6 Keyboard integration Figure 5-7 Example of unit 2 (debugger) output to the assigned window 2 on page Figure 5-8 Page 0, window arrangement Figure 5-9 Page 0, window arrangement Figure 5-10 Assigning scan codes to the individual keys Figure 5-11 Character table from 0 to 255 (0H to FFH), part Figure 5-12 Character table from 0 to 255 (0H to FFH), part Figure 5-13 Receiving data Figure 5-14 Sending data Figure 5-15 Master slave configuration with initiation conflict Figure 5-16 Structure of the RMOS3 driver functions Programming Manual, 07/2012, A5E

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

12 About this manual Notations 1.2 Notations We use the following notation to enhance legibility of the RMOS3 documentation: Commands Commands control program sequences in dialog or batch mode. The Courier font is used in the text to highlight the commands. A command consists of at least one element. Elements are constants or variables. They are comprised of letters, numbers and special characters (e.g. #*?). The Courier font is also used to present program listings. They are printed in compliance with the characters and do not follow the notation for commands. The programming language C, for example, distinguishes between uppercase and lowercase notation. Table 1-1 Commands Representation Property Comment UPPERCASE Constant Elements in uppercase notation represent constants. Entries are made in accordance with the character notation with support of uppercase and lowercase letters Constant Numbers are always constants. x Variable Elements in lowercase notation represent variables that can be replaced by current elements. ()\:;> Special characters Special characters and whitespaces serve as delimiters between elements and always need to be entered. The use of elements is described by meta characters. Meta characters are not entered. Representation Property Comment < > Delimiters Variables are enclosed in angled brackets [ ] Optional Elements in angled brackets are optional. a b c Selection An element can be selected if several elements are arranged vertically in braces or horizontally between vertical lines.... Repetition Ellipses indicate a possible repetition of the previous element. Abbreviations A number of abbreviations and short names apply to the entire RMOS3 documentation: Table 1-2 Abbreviations Abbreviation Meaning Text passage cfg configurable System calls uintmax maximum unsigned integer (FFFF FFFFH) System calls dp data pointer (sel:off) 48-bit pointer System calls 12 Programming Manual, 07/2012, A5E

13 About this manual Notations Data types The following data types may be used for the C compilers approved for RMOS3: Table 1-3 General data types Data type char short int long long long 1 void _FAR * 2 void _NEAR * 2 enum float double Data length 8 bit 16 bit 32 bit 32 bit 64 bit 48 bit 32 bit 32 bit 32 bit 64 bit 1 Only available for GNU programs. 2 Pointers in flat programs always have a length of 32 bit. No distinction is made between NEAR and FAR. Table 1-4 Data types of the RMOS3 API Name Data type Data length uchar unsigned char 8 bit ushort unsigned short 16 bit uint unsigned int 32 bit ulong unsigned long 32 bit rmfarproc 1 rmnearproc 1 rmproc 1 Pointer to function type void _FAR f(void) Pointer to function type void _NEAR f(void) Pointer to function type void _NEAR f(void) 48 bit 32 bit 32 bit 1 Pointers in flat programs always have a length of 32 bit. No distinction is made between NEAR and FAR. Programming Manual, 07/2012, A5E

14 About this manual Notations 14 Programming Manual, 07/2012, A5E

15 Function groups 2 The chapter lists the expressions used to program RMOS3 in their logical context. If using the functions of a group in reloadable tasks or programs, you need to provide the corresponding library during linking: For GNU compilers: RMOS3 kernel functions CLI functions C library functions libhlig.a libclig.a libcrig.a 2.1 RMOS3 functions RMOS3 V3.11 or higher offers a new application programming interface (API). The API is a pure function interface, with the return value of the function generally providing information related to the sequence (error code etc.). The function may also return notes. This API is supplied as library for compilers with segmented memory model and for compilers with FLAT memory model. Certain calls (descriptor operations, configuration calls) are not implemented in the FLAT interface. Programs and tasks that output calls to RMOS3 in accordance with V3.0 or earlier can still be executed. RMAPI.H is included as header file with the prototypes for the API. This file, in turn, includes the RMTYPES.H (SVC specific type definitions) and RMDEF.H (general definitions such as error codes etc.) files. The RMCOMP.H header file contains macros for customizing the application to the different C compilers and memory models. These macros are used by other include files (RMAPI.H, CRUN). The header file SVC.H is only required for SVCs to be migrated from an interface for RMOS3 V3.0. Programming Manual, 07/2012, A5E

16 Function groups 2.1 RMOS3 functions 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..23 for APIC) is valid on the PC. 16 Programming Manual, 07/2012, A5E

17 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 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 RmInitOS RmResetOS RmRunOS RmSetOS RmSetPutcharProc RmSetSMRCount RmSetSVC Adapt dynamic to static resource IDs Pass start addresses of the subprograms for hardware operation Start operating system configuration Initialize all driver units Run system configuration Publish the address of function putchar() Set SMR limit Initialize SVC table Programming Manual, 07/2012, A5E

18 Function groups 2.1 RMOS3 functions Memory RmAlloc RmCreateMemPool RmDeleteMemPool RmExclude RmFree RmFreeAll RmGetSize RmMemPoolAlloc RmReAlloc RmGetMemPoolInfo Allocate HEAP memory area Create dynamic memory pool Delete dynamic memory pool Reserve memory pool area Release memory area for specific task Release all memory areas for specific tasks Get memory area length Allocate memory area from memory pool Change memory area size Get information on memory pool Descriptors RmChangeDescriptor RmChangeDescriptorAccess RmCreateDescriptor RmDeleteDescriptor RmGetLinAddress RmGetPhysAddress RmMapMemory Change descriptor Change descriptor access rights Create descriptor Delete descriptor Get linear address from pointer Get physical address of a memory area Address physical memory Task control RmActivateTask RmBindTask RmCreateTask RmCreateChildTask RmCreateTaskEx RmDeleteTask RmDisableScheduler RmEnableScheduler RmEndTask RmGetBindTaskInfo RmGetTaskID RmGetTaskInfo RmGetTaskPriority RmGetTaskState RmKillTask RmPauseTask Activate task Bind task to core Registers static or reloadable task with the operating system Registers static or reloadable task with the operating system Define dynamic task Delete dynamic task Disable scheduler Enable scheduler End task Get task binding information Get task ID Get task information Get task priority Get task state Set task to DORMANT or NON-EXISTENT state Wait for expiration of time interval 18 Programming Manual, 07/2012, A5E

19 Function groups 2.1 RMOS3 functions RmQueueStartTask RmRestartTask RmResumeTask RmSetTaskPriority RmStartTask RmSuspendTask Add task start request to queue. The task is started as soon as it is in DORMANT state. End and then restart the task on expiration of the time interval. Terminate interval that was initiated with RmSuspendTask or RmPauseTask Change task priority Task start request for tasks in DORMANT state. Set task to BLOCKED state Resources RmCatalog RmGetEntry RmGetName RmList RmUncatalog Enter resource in resource catalog Find catalog entry Search catalog for entry List catalog entries Remove resource from catalog Messages RmCreateMessageQueue RmDeleteMessageQueue RmReadMessage RmSendMessage RmSetMessageQueueSize Create message queue Clear message queue Fetch message from message queue Add message to message queue Set message queue length Mails RmCreat box RmDelet box RmReceiv RmSendMail RmSendMailCancel RmSendMailDelayed RmSetMailboxSize Define dynamic mailbox Delete dynamic mailbox Receive mail from local mailbox Send mail to local mailbox Cancel timer that was started with RmSendMailDelayed Transfer mail to mailbox with time-delay Set mailbox limits Programming Manual, 07/2012, A5E

20 Function groups 2.1 RMOS3 functions Flags RmCreateFlagGrp RmDeleteFlagGrp RmGetFlag RmResetFlag RmResetLocalFlag RmSetFlag RmSetFlagDelayed RmSetLocalFlag Define dynamic flag group Delete dynamic flag group Test event flag Reset event flag Reset local event flag Set event flag Set event flag on expiration of an interval Set local event flag Semaphores RmCreateBinSemaphore RmDeleteBinSemaphore RmReleaseBinSemaphore RmGetBinSemaphore Define dynamic semaphore Delete dynamic semaphore Reset semaphore Test and set semaphore SpinLocks RmInitSpinLock RmGetSpinLock RmGetSpinLockIRQ RmReleaseSpinLock RmReleaseSpinLockIRQ Initialize SpinLock Request SpinLock Request SpinLock and disable interrupts Release SpinLock Release SpinLock and enable interrupts Time management RmSetSystemTime RmGetSystemTime RmSetHWClockTime RmGetHWClockTime RmGetAbsTime RmGetSystemPeriod Set date and time Transfer date and time from the system Set date and HW clock Transfer date and HW clock Transfer date and absolute time from the system Query system clock rate 20 Programming Manual, 07/2012, A5E

21 Function groups 2.1 RMOS3 functions Fast cycle times RmInitFastTick RmRemoveFastTick RmInitFastTask RmRemoveFastTask Initialize fast cycle with time pattern shorter than one millisecond Remove fast cycle Start task in fast cycle Remove task from fast cycle HPET functions RmInitHPET Initialize function for reading HPET timer 0 RmGetTimeHPET0 Read current counter of HPET timer 0 RmGetPeriodHPET0 Query period of HPET timer 0 Drivers RmCreateDriver RmCreateUnit RmIO RmResumeDriver RmSuspendDriver Register static or reloadable driver at the operating system Register unit at the operating system Request I/O operation Define new device driver Suspend device driver (set to BLOCKED state) System RmDecode RmGetSysB Decode RMOS3 error number Read System Control Block Interrupt handlers RmGetIntHandler RmReserveInterrupt 1 RmRestoreIntHandler RmSetIntDIHandler RmSetIntISHandler RmSetIntTaskHandler RmSetIntMailboxHandler RmSetDeviceHandler 1 RmSetIntDefHandler Read interrupt handler Reserve interrupt Restore DI interrupt handler in GNU Set DI interrupt handler Set S or I interrupt handler Set task start by interrupt handler Set mailbox interrupt handler Create driver interrupt handler Install default interrupt handler 1 Effective only at system startup Programming Manual, 07/2012, A5E

22 Function groups 2.1 RMOS3 functions Interrupt handlers on the PCI bus RmPciSearchFunction RmPciSearchSubFunction RmIntShSrv RmInitShIntClient RmSetShIntISHandler1 RmSetShIntISHandler2 RmClrShIntISHandler Scan the PCI bus for PCI devices (vendor and device ID) Scan the PCI bus for PCI devices and their subsystem IDs (vendor and device ID) Initialize Shared Interrupt Server Initialize Shared Interrupt Client Install Shared Interrupt Handler in compatibility mode Install Shared Interrupt Handler in fast mode Delete Shared Interrupt Handler Miscellaneous RmHookException RmSetProfilerPoint Hook callback function that is called on exception Set orientation points in the profiler for "Task Activity" measurement 22 Programming Manual, 07/2012, A5E

23 Function groups 2.1 RMOS3 functions 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 RcGetCMOSDateTime RcGetCMOSSize RcDummyGetClock RcGetFloppyType RcGetHardDiskType RcRAMSize RcInit3964 RcInit3964r8250 RcInit3964r8530 RcInit3964rCOM1 RcInit3964rCOM2 RcInit8254 RcInit8259A RcInitByt RcInitByt8250 RcInitByt8251 RcInitByt8255 RcInitByt8530 RcInitBytCOM1 RcInitBytCOM2 RcInitBytEga RcInitBytLPT1 RcInitBytLPT2 RcInitCLIDispatcher RcInitCrt RcInitCrt8250 RcInitCrtCOM1 RcInitCrtCOM2 RcInitDEBDispatcher RcInitDebugger RcInitEmul RcInitErrorLogger RcInitFd0 RcInitHd0 EOI routine for PC compatible modules Read date and time from the CMOS clock (PC) Read length of RAM from CMOS RAM (PC) Dummy function Read type and ID of floppy drives from CMOS RAM Read HDD type from CMOS RAM Configure RAM size Register 3964 driver in RMOS3 Register 8250 block at the 3964 driver Register 8530 block at the 3964 driver Register COM1 interface at the 3964 driver Register COM2 interface at the 3964 driver Initialize 8254 timer Initialize 8259A interrupt controller Register BYT driver in RMOS3 Register 8250 block at the BYT driver Register 8251 block at the BYT driver Register PC line printer at the BYT driver Register 8530 block at the BYT driver Register COM1 interface at the BYT driver Register COM2 interface at the BYT driver Register EGA display adapter at the BYT driver Register LPT1 at the BYT driver Register LPT2 at the BYT driver Create dispatcher task for debugger and CLI Register CRT driver in RMOS3 Register 8250 block at the CRT driver Register COM1 interface at the CRT driver Register COM2 interface at the CRT driver Create dispatcher task without CLI Create debugger Initialize co-processor emulator Create error logger task Register PC floppy driver in RMOS3 Register PC HD driver in RMOS3 Programming Manual, 07/2012, A5E

24 Function groups 2.1 RMOS3 functions RcInitHsfs RcInitNPX RcInitPasspoint8250 RcInitPasspoint8251 RcInitPasspoint8530 RcInitPasspointEga RcInitPICPC RcInitRamdisk RcInitRamdisk32 RcInitRemoteTask RcInitReporter RcInitReporterX RcInitTimerPC RcInitUserTask RcPutchar8250COM1 RcPutchar8250COM2 RcPutchar8251 RcPutchar8530 RcPutcharEga RcScanRAMSize RcSetCMOSDateTime RcSetDummyDateTime RcSetFloppyType Allocate resources for HSFS Initialize co-processor Initialize 8250 block Initialize 8251 block Initialize 8530 block Initialize EGA adapter Initialize interrupt controller on PC hardware Register RAM disk driver in RMOS3 Register RAM disk driver in RMOS3 Create remote task Create reporter task Create ReporterX task Initialize 8254 timer on PC hardware Create user task Output character to 8250 block (COM1) Output character to 8250 block (COM2) Output character to 8251 block Output character to 8530 block Output character to EGA adapter Query RAM length (with memory test) Set date and time of the CMOS clock (PC) Dummy function Set type and ID of floppy drives in CMOS RAM (PC) 24 Programming Manual, 07/2012, A5E

25 Function groups 2.1 RMOS3 functions Miscellaneous functions Overview This chapter describes special functions. Corresponding information is available in Reference Manual Part IV. Task start parameters get2ndparm getparm getdword Read task start parameter EBX Read task start parameter as pointer Read task start parameter as long value Task operations stl_load stl_free Load task De-allocate task HDD functions x_hd_init Integration of one or several HD partitions into the HSFS System functions for BUSY task x_bu_init x_bu_get Initialize BUSY task Query average system idle time in percent Programming Manual, 07/2012, A5E

26 Function groups 2.2 CLI functions 2.2 CLI functions 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 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. 26 Programming Manual, 07/2012, A5E

27 Function groups 2.2 CLI functions Short description of the CLI functions RMOS3 programs can utilize the following CLI functions. For information about these functions, refer to Reference Manual Part IV. x_cli_cancel Cancel job started with x_cli_extended_session or x_cli_extended_start. x_cli_cmdexec Execute CLI command x_cli_cmdline Read command line and process any redirection character that was possibly read x_cli_errorlevel Read error level x_cli_extended_session Start foreground job x_cli_extended_start Start background job x_cli_get_device Determines whether a given name is a device name. If yes, the device and unit numbers will be returned. x_cli_inhibit_abort Inhibit command abortion across a specific period, or permit it again x_cli_inhibit_control_c Inhibit command abortion with <CTRL>+C x_cli_init_manager Initialize CLI program manager x_cli_job_command Returns a pointer to the command line that was used to start a job x_cli_job_command_tail Returns a pointer to the parameters which were used to start a job x_cli_prompt Returns the current prompt in expanded form. x_cli_restart_job_pl0 Restart application at privilege level 0 x_cli_session Start foreground job x_cli_start Start background job x_cli_test_abort Determines whether an attempt was made to abort a job with <CTRL>+C or cancel while this action was inhibited. x_cli_truename Convert file name to file name with absolute path Programming Manual, 07/2012, A5E

28 Function groups 2.3 C library functions 2.3 C library functions 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 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. 28 Programming Manual, 07/2012, A5E

29 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. Programming Manual, 07/2012, A5E

30 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. 30 Programming Manual, 07/2012, A5E

31 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 chdir changevib checkpoint chmod clearerr close createvib dismount duread duwrite fclose fduopen fdureopen feof ferror fflush fgetc fgetpos fgets fileno fopen fprintf fputc Verify access to file Change current working directory Change description block of data volume Save data from (HSFS) intermediate file buffer Change file attributes Reset stream error status Close file Create new description block of data volume Log off device from HSFS file system Read character by means of RMOS3 driver Write character by means of RMOS3 driver Close stream Open stream to RMOS3 driver Redirect stream to driver Query stream status after EOF Query stream status after I/O error Flush stream buffer Read character from stream Return current position in file Read string from stream Determine file descriptor Open stream Formatted output to stream Write character to stream Programming Manual, 07/2012, A5E

32 Function groups 2.3 C library functions fputs fread freopen fscanf fseek fsetpos ftell fwrite getc getchar getcwd gets getvolumestatus getw lseek mkdir mount open printf putc putchar puts putw read remap remove rename rewind rmdir scanf search setbuf setvbuf sprintf sscanf tmpfile tmpnam ungetc unlink vfprintf vprintf vsprintf write Write string to stream Read data from stream Replace file assigned to a stream Formatted input from stream Position data pointer in stream Set current position in file Determine data pointer in stream Write data to stream Read character from stream Read character from the standard input Determine current working directory Read string from stream Get status information of data volume Read word from stream Position data pointer in file Create directory Mount device in HSFS Open file for read/write access Formatted output to standard output Write character to stream Write character to standard output Write string to stream Write word to stream Read data from file Format data volume Remove file Rename file Position data pointer in stream Delete directory Formatted input from standard input Search for files Set stream buffer Set stream buffer Formatted output to string Formatted input from a string Create temporary file Create name for temporary file Write back character to stream Formatted output to stream Formatted output to stream Formatted output to stream Formatted output to string Write data to file 32 Programming Manual, 07/2012, A5E

33 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 _toupper isalnum isalpha isascii iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit toascii tolower toupper Convert characters to lowercase Convert characters to uppercase Specify whether a character is alphanumerical Specify whether a character is alphabetical Specify whether a character is an ASCII character Specify whether a character is an ASCII control character Specify whether a character is a decimal number Specify whether a character is printable Specify whether a character is a lowercase letter Specify whether a character is printable Specify whether a character is a punctuation mark Specify whether a character is a whitespace Specify whether a character is an uppercase letter Specify whether a character is a hexadecimal number Convert character to integer Convert character to lowercase 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 atoi atol strcat strchr strcmp strcpy strcspn strlen strncat strncmp strncpy strpbrk strrchr strspn strstr strtod strtok strtol strtoul Convert string to double number Convert string to integer Convert string to long integer Append string to second string Search for character in a string Compare two strings Copy string to second string Compare two strings Get string length Append string segment to second string Compare two string segments Copy string segment Compare characters in two strings Search for character in a string Compare two strings Compare two strings Convert string to double number Find character unequal to delimiter in string Convert string to long integer Convert string to unsigned long integer Programming Manual, 07/2012, A5E

34 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 memchr memcmp memcpy memmove memset Copy character from source to target Find character Compare content of two memory ranges Copy character from source to target Copy character from source to target 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 realloc malloc Release memory Change length of memory space 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 acos asin atan atan2 ceil cos cosh div exp fabs floor fmod frexp labs ldexp Calculate absolute value of an integer Arc cosine Arc sine Arc tangent Arc tangent of two double numbers Round double number Cosine Cosine hyperbolicus Integer division Exponential function Calculate absolute value of double number Round down a double number Determine division remainder from two double numbers Split double number Determine absolute value of long integer Generate double number 34 Programming Manual, 07/2012, A5E

35 Function groups 2.3 C library functions ldiv log log10 matherr modf pow rand sin sinh sqrt srand tan tanh Long integer division Natural logarithm Decadic logarithm Application-specific error handling Split double number into integer and fraction Power function Generate random integer Sine Sine hyperbolicus Square root function Set init value for rand Tangent Tangent hyperbolicus Time and date functions Control 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 ctime _ctime32 difftime gmtime Convert date and time to string Convert date and time to string Convert date and time to string (for time data beyond January 19, 2038) Determine length of period 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 strftime time _time32 tzset Convert local time Output formatted date and time Calculate system time since , 00:00:00 GMT Calculate system time since , 00:00:00 GMT (for time data beyond January 19, 2038) Set time zones The control functions are required to end tasks and are declared in the STDLIB.H and TASK.H header files. abort assert atexit exit x_cr_killtsk inhibitabort End task Abort task conditionally Specify the routines to call on task completion Clear task and exit with defined state Delete task Inhibit task abortion by means of CTRL C (IO.H) Programming Manual, 07/2012, A5E

36 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 perror strerror sys_nerr sys_errlist Error numbers of system calls and library functions Ouput CRUN error message Get error text Number of entries in sys_errlist String array of error messages Miscellaneous functions Summary of functions that cannot be assigned unambiguously to a class. bsearch getenv longjmp putenv qsort raise setjmp signal sleep x_cr_gettaskid x_cr_gettaskparam x_cr_initenv x_cr_setexit xinitc xinitt Find element in sorted table Get environment variable Execute non-local jump Change or add environment variable Sorting function Trigger signal Set mark for non-local jump Install exception handling function (signal handler) Stop task for a specific time Get ID of the calling task Determine stdin, stdout, stderr and the task environment Initialize task environment Set task-specific exit handler Initialize CRUN Execute task-specific initialization of CRUN 36 Programming Manual, 07/2012, A5E

37 Function groups 2.4 Driver functions 2.4 Driver functions 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. Programming Manual, 07/2012, A5E

38 Function groups 2.4 Driver functions Short description of the driver functions Assembler _ELIPSE X_SYSTATE X_SYSTATE_SW X_XEL X_XEL_SW Transition from DI to I state Transition from I to S state Transition from I to S state without EOI Change from I state to scheduler Change from I state to scheduler without EOI Assembler and C XCATALOG XCHANGEDESC XCHANGEDESCACCESS XCREATEDESC XDELDESC XDELTMB XDEVDATA XDQTMB XDWORD XERRLOG XEXSYS XGETSMR XHALOC XHDALOC XIODONE XOVER, xjmp_xover XPHYSADR XPUTSMR XQPIRB XQSETUNS XQSIRB XQSTRT XQTMB XRECV XREF XSEF XSEND XSETUNS XSYSTEM XTEF XTIMEOUT Enter in the RMOS3 resource catalog Change descriptor base and/or limits Change descriptor access byte Create descriptor Delete the descriptor specified by means of selector Remove TMB from monitoring list Calculate XDCB and XUCB according to XDEVNUM and XDEVUNIT Exclude TMB from the monitoring list without releasing it Convert the offset address of an RMOS3 data variable to doubleword address Log error at the system console, if available (error logger task) Exit the S state (end system process) Request system memory block Allocate pool memory space Release memory space Complete processing of SVC RmIO for type I drivers Completion of I/O request for type II drivers in C Determine physical address Return system memory block Add active IRB to the queue of a parallel driver Queue start of user task for unexpected interrupts Add active IRB to the queue of a serial driver Add task start request to queue Add TMB from monitoring list Receive mail from local mailbox Reset event flag Set event flag Send mail to local mailbox Start user task for unexpected interrupts Transition from DI to System state Test event flag Set device timeout (only type II drivers) 38 Programming Manual, 07/2012, A5E

39 Function groups 2.4 Driver functions System variables for parameter transfer The following variables are used to pass parameters to the subprograms of the nucleus and to pass parameters returned by the operating system kernel. All variables may only be used in S state. Name Description Length XCIRB Address of the current I/O request block (IRB) 6 bytes XDEVNUM Current driver ID 1 byte XDEVUNIT Current device ID 1 byte XUCB Current UCB address 6 bytes XDCB Current DCB address 6 bytes XERRMSG Error message address 6 bytes XOFFSET OFFSET address; general usage 4 bytes XPOINTER OFFSET/SEGMENT address; general usage 6 bytes XSTATUS Status data to return to the task 8 bytes XTUNIT Time interval for timers 1 byte XTNUM Number of time intervals for timers 1 byte XPOOLNUM Memory pool ID for XHALOC and XHDALOC 1 byte XBLKLEN Number of bytes for XHALOC and XHDALOC 4 bytes XSEQ Sequential number of current IRB 2 bytes XSEG Selector for segment handling 2 bytes XSEGLIM Segment limit 4 bytes XTASK Task ID 2 bytes XPRIS Options for priority source 1 byte XPRIV Priority to use 1 byte XP1 Parameter 1 4 bytes XP2 Parameter 2 4 bytes XGRP Global event flag ID 1 byte XFLAGS Mask for flag group 4 bytes XBOX Local mailbox ID 1 byte XGENB Byte for general usage 1 byte XGENW Word for general usage 2 bytes XGEND Dword for general usage 4 bytes 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. Programming Manual, 07/2012, A5E

40 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 ;code 2: read a block DD WRITE_BLK ;code 3: write a block DD CLEAR_UNIT ;code 4: reset unit The nucleus jumps directly to the procedures identified by the addresses in the table if requests to the driver with corresponding functions are pending. The nucleus, for example, directly calls the WRITE_BLK procedure if a request with function code 3 is pending. Note The jump table in RMOS3 consists of offset addresses (32-bit). The code must be available in segment RM3_CODE32. Reserving and releasing devices The reserve and release functions are implemented directly in the operating system kernel for type II drivers. Only the task that has reserved the device may release it. When bit 7 of parameter Function is set and the I/O device is currently processing an I/O request, the priority of the I/O request is raised to 255 and the IRB block is written to the first position in the queue after any preemptive requests that may already be queued. A reservation of the device by another task is ignored. Handling timeouts Type I drivers must completely process timeout events. This gives the programmer more scope. Although the nucleus handles timeout events at type II drivers, the driver can actually handle the event by itself. Status bits The nucleus sets and resets bit 0 (status) of DCB_STS or UCB_STS (sequential/parallel) for type II drivers. 40 Programming Manual, 07/2012, A5E

41 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. Programming Manual, 07/2012, A5E

42 Function groups 2.4 Driver functions 42 Programming Manual, 07/2012, A5E

43 Data structures RmAbsTimeStruct Syntax #include <rmtypes.h> typedef struct _RmAbsTimeStruct { ulong lotime; ulong hitime; }RmAbsTimeStruct; Description Contains the system time and date (absolute system time) and is used by the RmGetAbsTime and RmSetAbsTime SVCs. Field Type Meaning lotime ulong Least significant segment of the absolute time hitime ulong Most significant segment of the absolute time See also RmGetAbsTime, RmSetAbsTime Programming Manual, 07/2012, A5E

44 Data structures 3.2 RmAsciiTimeStruct 3.2 RmAsciiTimeStruct Syntax #include <rmtypes.h> typedef struct _RmAsciiTimeStruct { char day[2]; /* (ASCII) */ char delim0; /* ' ' */ char month[3];/* JAN... DEC (ASCII) */ char delim1; /* ' ' */ char year[4]; /* (ASCII) */ char blank; /* ' ' */ char hour[2]; /* (ASCII) */ char colon0; /* ':' */ char min[2]; /* (ASCII) */ char colon1; /* ':' */ char sec[2]; /* (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 44 Programming Manual, 07/2012, A5E

45 Data structures 3.3 RmDCDStruct 3.3 RmDCDStruct Syntax #include <rmtypes.h> typedef struct _RmDCDStruct { struct _RmUCDStruct _NEAR * ucd; uchar units; uchar shr; rmproc init; rmproc svc; uchar flags; uchar fmax; #if RM3 uchar res[4]; #else uchar res[2]; #endif }RmDCDStruct; Description The RmDCDStruct structure defines a structure for driver control data Field Type Meaning ucd Pointer to RmUCDStruct UCD address units uchar Reserved shr uchar Device number of a shared device (0FFH=no sharing) init rmproc Address of the driver init routine svc rmproc Address of the RmIO entry point flags uchar Bit Meaning 0=1 Parallel driver 0=0 Sequential driver 1=1 Type II driver 1=0 Type I driver 2=0 Driver is initialized after system init 2=1 Driver is not initialized after system init and suspended (in BLOCKED state) fmax uchar Maximum function code of the driver res[24] uchar Reserved See also RmIO RmUCDHeadStruct (Page 67) RmUCDStruct (Page 68) Programming Manual, 07/2012, A5E

46 Data structures 3.4 RmEntryStruct 3.4 RmEntryStruct Syntax #include <rmtypes.h> typedef struct _RmEntryStruct { uchar slen; char string[16]; uchar type; ulong ide; ushort id; }RmEntryStruct; Description The RmEntryStruct structure is used in SVCs RmList and RmGetEntry to read catalog entries. Field Type Meaning slen uchar Length of next string. string char[16] String containing a resource name. type uchar Sets the resource type. The following values are possible: Value RM_CATALOG_TASK RM_CATALOG_DEVICE RM_CATALOG_POOL RM_CATALOG_SEMAPHORE RM_CATALOG_EVENTFLAG RM_CATALOG_CNTRL RM_CATALOG_LOCALMAILBOX RM_CATALOG_MISC RM_CATALOG_USER RM_CATALOG_UNIT RM_CATALOG_MESSAGE RM_CATALOG_ALL Meaning Task Device driver (Device) Memory pool Semaphore Global event flag Monitored program access Local mailbox Reserved User-defined type Device (Unit) Messages 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 46 Programming Manual, 07/2012, A5E

47 Data structures 3.5 RmIntrhandMailStruct 3.5 RmIntrhandMailStruct Syntax #include <rmtypes.h> typedef struct _RmIntrhandMailStruct { uint int_no ; uint int_vec :8 ; uint int_kind :1 ; uint lost_int_overflow :1 ; #if RM3 uint dummy_2 :22 ; #else uint dummy_2 :6 ; #endif ushort lost_int; #if RM3 ushort dummy_3; #endif }RmIntrhandMailStruct Description SVC RmSetIntMailboxHandler can be used to define interrupt handlers for sending mails to a mailbox. The RmIntrhandMailStruct structure defines the format of this mail that is saved to the mailbox after the corresponding interrupt was triggered. The structure consists of altogether three 23-bit words Field Type Meaning int_no uint Specifies the interrupt number. int_vec 8-bit Specifies the associated interrupt vector. int_kind 1-bit Identifies the interrupt type: Value Meaning 0 Hardware interrupt 1 Software interrupt lost_int_ 1-bit This bit is set (= 1) if interrupts were lost. overflow dummy_2 22 bit Reserved lost_int 8-bit Specifies the number of lost interrupts. dummy_3 24-bit Reserved See also RmSetIntMailboxHandler Programming Manual, 07/2012, A5E

48 Data structures 3.6 RmIOStatusStruct 3.6 RmIOStatusStruct Syntax #include <rmtypes.h> typedef struct _RmIOStatusStruct { char primary; char secondary; ushort count; #if RM3 ushort status3; ushort status4; #endif }RmIOStatusStruct; Description The RmIOStatusStruct structure defines a structure to which return values are saved on completion of I/O requests (RmIO) Field Type Meaning primary char First status byte secondary char Second status byte count ushort Number of bytes transmitted status3 ushort Third status word status4 ushort Fourth status word See also RmIO 48 Programming Manual, 07/2012, A5E

49 Data structures 3.7 RmIRBStruct 3.7 RmIRBStruct Syntax #include <rmtypes.h> typedef struct _RmIRBStruct { struct _RmIRBStruct _NEAR * link; ushort pri; struct _RmTCBStruct _NEAR * tcb; struct _RmUCBStruct _NEAR * ucb; struct _RmTMBStruct _NEAR * tmb; uchar rio; uchar funct; uchar device; uchar unit; uchar grp; uint flags; void * status; #if RMFLAT ushort status_seg; #endif void * bufr; #if RMFLAT ushort bufr_seg; #endif ushort seq; }RmIRBStruct; Description The RmIRBStruct structure defines a structure for I/O requests (RmIO). Field Type Meaning link Pointer to RmIRBStruct Forward link or 0 pri ushort Priority tcb Pointer to RmTCBStruct TCB address of the requesting task ucb Pointer to RmUCBStruct UCB address of the requested device tmb Pointer to RmTMBStruct TMB address of current request rio uchar Start of SDB image funct uchar Function code device uchar Driver ID unit uchar Device ID grp uchar Flag group (always zero) flags uint Flag mask status void* Address of status buffer status_seg ushort Fill word for FLAT model bufr void* Address of the device-specific parameter list bufr_seg ushort Fill word for FLAT model seq ushort Reserved See also RmIO Programming Manual, 07/2012, A5E

50 Data structures 3.8 RmMailboxStruct 3.8 RmMailboxStruct Syntax #include <rmtypes.h> typedef struct _RmMailboxStruct { void *adr; #if RMFLAT ushort adr_res; #endif #if RM3 ushort pqd; #endif uint len; }RmMailboxStruct; Description RmMailboxStruct is used for indirect transmission of a message via the mailbox by transferring the memory address and message length in the mailbox instead of the actual message. Field Type Meaning adr void* Contains a pointer to the memory address of the message. adr_res ushort Fill word for FLAT model pad ushort If adr is a FAR pointer it comprises 48 bits. pad is padded to 64 bits. len uint Specifies the message length. See also RmSendMail, RmReceiv 50 Programming Manual, 07/2012, A5E

51 Data structures 3.9 RmMailIDStruct 3.9 RmMailIDStruct Syntax #include <rmtypes.h> typedef struct _RmMailIDStruct { ulong low; ulong high; }RmMailIDStruct; Description Field Type Meaning low ulong Least significant segment of the mail ID high ulong Most significant segment of the mail ID See also RmSendMailCancel, RmSendMailDelayed Programming Manual, 07/2012, A5E

52 Data structures 3.10 RmMemPoolInfoStruct 3.10 RmMemPoolInfoStruct Syntax #include <rmtypes.h> typedef struct _RmMemPoolInfoStruct { ulong pool_size; ulong avail_mem_size; ulong max_block_size; ulong reserved[5] }RmMemPoolInfoStruct; Description Return value of function RmGetMemPoolInfo. The return value contains information about the specified memory pool. Field Type Meaning pool_size ulong Total length of the memory avail_mem_size ulong Total length of available memory max_block_size ulong Length of the largest memory block (always -1) See also RmGetMemPoolInfo 52 Programming Manual, 07/2012, A5E

53 Data structures 3.11 RmSpinLockStruct 3.11 RmSpinLockStruct Syntax #include <misc86.h> struct _RmSpinLockStruct { uchar Spin; uchar CoreID; uchar Reserved; uchar Count; uint Interruptflags; } GNU_PACKED; typedef struct _RmSpinLockStruct RmSpinLockStruct; Description Return value of function RmInitSpinLock. Contains information about the initialized SpinLock. Field Type Meaning Spin uchar 1, if SpinLock is occupied, 0 if free CoreID uchar Core on which the SpinLock was requested Reserved uchar For internal use Count uchar Number of times the SpinLock was requested on the same core Interruptflags uint Flags for the interrupt state See also RmInitSpinLock, RmGetSpinLock, RmGetSpinLockIRQ, RmReleaseSpinLock, RmReleaseSpinLockIRQ Programming Manual, 07/2012, A5E

54 Data structures 3.12 RmSysB 3.12 RmSysB Syntax #include <rmtypes.h> typedef struct _RmSysB { uchar version[6]; ushort proctype; ushort systemtype; ushort res1; ulong reserved; char statname[16]; uchar bootfname[128]; uchar bootnode[6]; uchar bootdrive; uchar res2; ulong ram_size; uint smr_max; uint smr_used; uint smr_avail; uint out_of_smr_count; #if RM3 ushort fl_er_sel; ushort fl_rw_sel; #endif ushort rate_msec; ulong rate_usec; ulong pit_count; ushort timer_int; rmproc issue_eoi_entry; uchar pic_count; uchar pic_base[8]; uchar pic_mask[8]; #if RM3 uchar res3[3]; #else uchar fres3[1]; #endif int (_FAR _FIXED * set_pic_mask) (uint irq); #if RM3 #if RMFLAT ushort res4f; #endif ushort res4; #endif int (_FAR _FIXED * init_pit) (void); #if RM3 #if RMFLAT ushort res5f; #endif ushort res5; #endif int (_FAR _FIXED * set_rtc_entry) (RmTimeStruct*); #if RM3 #if RMFLAT ushort res6f; #endif ushort res6; #endif int (_FAR _FIXED * get_rtc_entry) (RmTimeStruct*); #if RM3 #if RMFLAT ushort res7f; #endif ushort res7; 54 Programming Manual, 07/2012, A5E

55 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: Bit pattern Single information 0x0F00 CPU type 0x00F0 CPU model (Pentium) 0x000F CPU stepping (Pentium) 0x8000 FPU available systemtype ushort 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 Programming Manual, 07/2012, A5E

56 Data structures 3.12 RmSysB 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 res2 ushort Reserved 5 Boot volume in bootfname ram_size ulong Size of RAM area in bytes smr_max uint Maximum number of SMRs smr_used uint Number of SMRs used smr_avail uint Available number of SMRs out_of_smr_count uint Specification of the number of times it was not possible to request new SMR areas fl_rw_sel ushort FLAT selector for code fl_rw_sel ushort FLAT selector for data rate_msec ushort RMOS3 system clock rate in milliseconds rate_usec ulong RMOS3 system clock rate in microseconds pit_count ulong Number of timer ticks between two timer interrupts timer_int ushort Interrupt number for timer issue_eoi_entry rmproc Address of the EOI function pic_count uchar Number of PICs pic_base[8] uchar Lowest vector address of PIC 1..8 (1=Master) pic_mask[8] uchar PIC masks for PIC 1..8 res3[3] uchar Reserved res3[1] uchar Reserved set_pic_mask (pointer to function) Function for manipulating the PIC mask res4f ushort Reserved res4 ushort Reserved init_pit (pointer to function) Function for timer initialization res5f ushort Reserved res5 ushort Reserved set_rtc_entry (pointer to function) Function for writing the real-time clock res6f ushort Reserved res6 ushort Reserved get_rtc_entry (pointer to function) Function for reading the real-time clock res7f ushort Reserved res7 ushort Reserved put_char_entry (pointer to function) Function putchar for nucleus outputs See also res8f ushort Reserved RmGetSysB 56 Programming Manual, 07/2012, A5E

57 Data structures 3.13 RmTaskInfoStruct 3.13 RmTaskInfoStruct Syntax #include <rmtypes.h> typedef struct _RmTaskInfoStruct { uchar pri; uchar state; uint*sp_ss; #if RM3 #if RMFLAT ushort sp_ss_res; #endif longlong rdy_time; #else uint rdy_time[3]; #endif char cpu_id; char flg; struct _RmTCDStruct *tcd_ptr; #if RMFLAT ushort tcd_ptr_res; #endif } RmTaskInfoStruct; Description Structure RmTaskInfoStruct defines the task data that SVC RmGetTaskInfo returns Field Type Meaning pri uchar Current task priority state uchar The two least significant bits define the task state Name RM_DORMANT RM_READY RM_BLOCKED RM_STA_EF RM_STA_SEMA RM_STA_LOAD RM_STA_STRT RM_STA_ENDT RM_STA_MSG RM_STA_MSGRCVD RM_STA_POOL RM_STA_HLT RM_STA_BREAK Meaning Task in DORMANT state. Task in READY state. 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: Waiting for event flag Waiting for semaphore Wait until target task is loaded. Waiting for start of the target task Waiting for end of the target task Waiting for receipt of message Waiting for receipt of transmitted message Waiting for allocation of memory pool space Stopped by DEBUGGER Interrupted by DEBUGGER breakpoint Programming Manual, 07/2012, A5E

58 Data structures 3.13 RmTaskInfoStruct Field Type Meaning RM_STA_PAUSE RM_STA_CNTRL RM_STA_WAIT Waiting for expiration of time interval (RmPauseTask) Waiting for completion of an I/O operation Wait for expiration of time interval RM_STA_ERR0 Runtime error, type 0 (Division by 0 Interrupt) RM_STA_ERR1 RM_STA_ERR2 RM_STA_ERR3 RM_STA_ERR4 RM_STA_ERR5 RM_STA_ERR6 RM_STA_ERR7 RM_STA_ERR8 RM_STA_ERR9 RM_STA_ERR10 RM_STA_ERR11 RM_STA_ERR12 RM_STA_ERR13 RM_STA_ERR14 RM_STA_ERR15 RM_STA_LOOK RM_STA_KEND RM_STA_KDEL RUNNING Runtime error, type 1 (Single Step Interrupt) Runtime error, type 3 (Breakpoint Interrupt) Runtime error, type 4 (Overflow Interrupt) Runtime error, type 5 (Array Bound Interrupt) Runtime error, type 6 (Unused Opcode) Runtime error, type 7 (Escape Opcode) Runtime error, type 8 (Double Fault) Runtime error, type 9 (NDP Segment Overrun) Runtime error, type 13 (General Protection) Runtime error, type 16 (Floating Point Error) Runtime error, type 10 (Invalid TSS) Runtime error, type 11 (Segment Not Present) Runtime error, type 12 (Stack Fault) Runtime error, type 14 (Page Fault) Runtime error, type 17 (Alignment Check) Wait for catalog entry End of task with SVC RmKillTask (e.g. on completion of the current I/O operation) Delete task with SVC RmKillTask (e.g. on completion of the current I/O operation) Task in RUNNING state. sp_ss uint Pointer to current stack pointer address sp_ss_res ushort Fill word for FLAT model rdy_time ulong Time of last change of the task to READY state cpu_id char Reserved, must be 0 flg char Task flags (Bits 7...0) tcd_ptr Pointer to RmTCDStruct TCD address tcd_ptr_res ushort Fill word for FLAT model 58 Programming Manual, 07/2012, A5E

59 Data structures 3.14 RmTCDStruct 3.14 RmTCDStruct Syntax #include <rmtypes.h> typedef struct _RmTCDStruct { uint eax; uint ebx; ushort ds; ushort es; char *stck; #if RMFLAT ushort stck_res; #endif rmfarproc task; #if RMFLAT ushort task_res; #endif #if RM3 char *load; #if RMFLAT ushort load_res; #endif /* RMFLAT */ #else uint efg[2]; #endif /* RM3 */ ushort time; uchar ovpri; uchar bpri; uchar inpri; uchar pid; ushort flags; ushort rr_ticks; #if RM3 uint efg[2]; #endif #if RM3 uchar reserve[4]; #else uchar reserve[2]; #endif }RmTCDStruct; Description Structure RmTCDStruct defines the TCD (Task Control Data) of an RMOS3 task. TCD contains the constants that the operating system needs to manage a task. TCDs for static tasks are configured using the RcInitUserTask functions and published to the system. TCDs for dynamic tasks are published to the system by means of SVC RmCreateTaskEx. An application may also receive a pointer to the TCD of a task by calling SVC RmGetTaskInfo. Meaning of the fields of the structure: Programming Manual, 07/2012, A5E

60 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 * Address of the load descriptor string for reloadable task, otherwise (char *) 0. load_res ushort Fill word for FLAT model efg uint Local event flag group. time ushort Time unit for timeout of the runtime-dependent priority control (see RM_TFL_OVPRI in the flags field). The time interval is calculated based on?? * time. The following values are possible: Symbolic name *) Time unit RM_TCD_MSEC_ ms RM_TCD_MSEC_ ms RM_TCD_MSEC_ ms RM_TCD_SEC 12 1 s RM_TCD_SEC_ s RM_TCD_MIN 16 1 min RM_TCD_MIN_ min HOUR 20 1 h *) 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 60 Programming Manual, 07/2012, A5E

61 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 RM_TFL_ NOHLT RM_TFL_ OVPRI RM_TFL_STK RM_TFL_DS Must be set if the task uses the numerical co-processor. The task cannot be stopped by other tasks. 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. 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 Programming Manual, 07/2012, A5E

62 Data structures 3.15 RmTimeStruct 3.15 RmTimeStruct Syntax #include <rmtypes.h> typedef struct _RmTimeStruct { uchar day; uchar month; ushort year; uchar hours; uchar minutes; uchar seconds }RmTimeStruct; Description Contains the system time and date (global system time) and is used by the RmGetHWTime and RmSetHWTime SVCs. Field Type Meaning day uchar Tag month uchar Month year ushort Year hours uchar Hours minutes uchar Minutes seconds uchar Seconds See also RmGetHWTime, RmSetHWTime 62 Programming Manual, 07/2012, A5E

63 Data structures 3.16 RmTMBStruct 3.16 RmTMBStruct Syntax #include <rmtypes.h> typedef struct _RmTMBStruct { /* *** Common part *** */ struct _RmTMBStruct _NEAR * link; uint ltime; uint htime; uchar type; union { /* *** Type 1 *** */ struct { uchar res; struct _RmUCBStruct _NEAR * ucb; void * sadr #if RMFLAT void * sadr_seg #endif } type_1; /* *** Type 2 *** */ struct { uchar res; struct _RmTCBStruct _NEAR * tcb; } type_2; /* *** Type 3 *** */ struct { uchar efgrp; struct _RmTCBStruct _NEAR * tcb; uint efmask; } type_3; /* *** Type 4 *** */ struct { uchar res; struct _RmTCBStruct _NEAR * tcb; } type_4; /* *** Type 5 *** */ struct { uchar res; struct _RmTCBStruct _NEAR * tcb; uchar ovpri uchar bpri uchar ovtime } type_5; /* *** Type 6 *** */ struct { uchar res; struct _RmTCBStruct _NEAR * tcb; uint swb; uint sem; } type_6; Programming Manual, 07/2012, A5E

64 Data structures 3.16 RmTMBStruct } utmb; }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; Description Structure RmTMBStruct defines a structure for timer monitoring blocks Field Type Meaning link Pointer to RmTMBStruct Forward link or 0 ltime uint Least significant DWORD of the absolute time htime uint Most significant DWORD of the absolute time type uchar TMB type: Value Meaning 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 RmUCBStruct UCB address sadr void* Address of the timeout routine sadr_seg ushort Fill word for FLAT model 64 Programming Manual, 07/2012, A5E

65 Data structures 3.16 RmTMBStruct TMB type 2 Field Type Meaning res uchar Reserved tcb Pointer to RmTCBStruct TCB address TMB type 3 Field Type Meaning res uchar Reserved efgrp uchar Event flag group tcb Pointer to RmTCBStruct TCB address efmsk uint Flag mask TMB type 4 Field Type Meaning res uchar Reserved tcb Pointer to RmTCBStruct TCB address TMB type 5 Field Type Meaning res uchar Reserved tcb Pointer to RmTCBStruct TCB address ovpri uchar Priority increment bpri uchar Priority limit ovtime uchar Priority time interval in ms TMB type 6 Field Type Meaning res uchar Reserved tcb Pointer to RmTCBStruct TCB address swb uint Address of the semaphore wait block sem uint Semaphore address Programming Manual, 07/2012, A5E

66 Data structures 3.16 RmTMBStruct TMB type 7 Field Type Meaning res uchar Reserved irb Pointer to RmIRBStruct IRB address TMB type 8 Field Type Meaning res uchar Reserved tjt uint Timeout jump table svc ushort Bit-coded SVC qh uint Specific queue header wb uint Specific wait block TMB type 9 Field Type Meaning res uchar Reserved alarm uint Alarm routine called on expiration tib uint Associated TIB See also RmTCDStruct (Page 59) 66 Programming Manual, 07/2012, A5E

67 Data structures 3.17 RmUCDHeadStruct 3.17 RmUCDHeadStruct Syntax #include <rmtypes.h> typedef struct _RmUCDHeadStruct { uchar pid; uchar intno; rmfarproc intadr; ushort uns; }RmUCDHeadStruct; Description Structure RmUCDHeadStruct defines the general structure of unit control data. Field Type Meaning pid uchar Reserved intno uchar Interrupt number intadr rmfarproc Interrupt vector address uns ushort Task ID for unexpected interrupt See also RmIO, RmUCDStruct (Page 68) Programming Manual, 07/2012, A5E

68 Data structures 3.18 RmUCDStruct 3.18 RmUCDStruct Syntax #include <rmtypes.h> typedef struct _RmUCDStruct { uchar pid; uchar intno; rmfarproc intadr; ushort uns; #if RM3 uchar port[256 10]; #else uchar port[128 8]; #endif }RmUCDStruct; Description Structure RmUCDStruct defines the general and a specific structure of unit control data. Field Type Meaning pid uchar Reserved intno uchar Interrupt number intadr rmfarproc Interrupt vector address uns ushort Task ID for unexpected interrupt port [256-10] uchar Device-dependent parameter See also RmIO, RmDCDStruct (Page 45), RmUCDHeadStruct (Page 67) 68 Programming Manual, 07/2012, A5E

69 Data structures 3.19 loader_result 3.19 loader_result Syntax #include <load.h> struct loader_result { ushort except_code; ushort shareable; char reserved_byte; ushort reserved_word2; uint code_seg_offset; ushort code_seg_base; uint stack_offset; ushort stack_seg_base; uint stack_size; ushort data_seg_base; char num_more_slots; ushort more_slots [1]; ushort reserved_word3; void _FAR *reserved_pointer1; }; typedef struct struct loader_result LOADER_RESULT; Description Structure loader_result defines the configuration of the loader result segment that the task loader generates while programs are loaded. The loader result segment contains the following information about a task loaded with stl_load function Field Type Meaning except_code ushort Return status of the load operation; contains the same value as the return status of function stl_load. Since the loader result segment is only created for successful load operations, only the 0 value and values in the range from 8100H to 810FH will be set for this segment. reserved_ word1 reserved_ byte reserved_ word2 ushort byte ushort Reserved. Reserved. Reserved. code_seg_ offset code_seg_ base stack_ offset stack_seg_ base uint ushort uint ushort Instruction pointer (EIP register); init value of the loaded task. Code segment (CS register); init value of the loaded task. Stack pointer (SP register); init value of the loaded task. Stack segment (SS register); init value of the loaded task. stack_size uint Stack size of the loaded task in bytes. Programming Manual, 07/2012, A5E

70 Data structures 3.19 loader_result Field Type Meaning data_seg_ base num_more_ slots ushort char 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. Number of segments assigned to the loaded task, including initialization data/stack/code segments. This value always equals 255, even if the task was assigned more than 255 segments. more_slots [1] ushort Field that contains all segment selectors of the loaded task. The length of the field is stored in num_more_slots. reserved_ ushort Reserved. word3 reserved_ pointer1 void* Reserved. See also stl_load 70 Programming Manual, 07/2012, A5E

71 Data structures 3.20 stdstruct 3.20 stdstruct Syntax #include <task.h> struct std_struct { int stdin_dev; int stdin_unit; int stdout_dev; int stdout_unit; int stderr_dev; int stderr_unit; char *stdin_fname; #if RMFLAT unsigned short stdin_fill; #endif char *stdout_fname; #if RMFLAT unsigned short stdout_fill; #endif char *stderr_fname; #if RMFLAT unsigned short stderr_fill; #endif char *tmp_path; #if RMFLAT unsigned short tmp_fill; #endif }; typedef struct std_struct STDSTRUCT; Description Structure STDSTRUCT defines the stdin, stdout I/O channels and error output channel stderr of a program. A channel can be defined based on the device/unit number combination, or on the file name Field Type Meaning stdxx_dev int A value >= 0 determines the number of an I/O driver (device number). Meaning of values < 0: Value Meaning 1 The file name specified in stdxx_fname is used. A new file is generated in the case of stdout and stderr. stdxx_unit is not used. 2 The file name specified in stdxx_fname is used. In the case of stdout and stderr the output data is appended to the end of the file, provided the file already exists. stdxx_unit is not used. 3 You should handle this value similar to stdxx_dev = 2, because the value only has the following meaning for the interactive CLI command START: The output file is inherited from the calling job and cannot be inherited by other jobs. stdxx_unit int If the value in stdxx_dev >= 0, stdxx_unit determines the number of an I/O device (unit number). If the value in stdxx_dev < 0, stdxx_unit is insignificant. Programming Manual, 07/2012, A5E

72 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 72 Programming Manual, 07/2012, A5E

73 Error codes and messages 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. Programming Manual, 07/2012, A5E

74 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 INT 0: INT 1: INT 3: INT 4: INT 5: INT 6: INT 7: INT 8: INT 9: INT 10: INT 11: INT 12: INT 13: INT 14: INT 16: INT 17: STRING DIVIDE ERROR AT ADDRESS: DEBUG EXCEPTION NEAR ADDRESS: BREAKPOINT EXCEPTION NEAR ADDRESS: OVERFLOW EXCEPTION NEAR ADDRESS: BOUNDS CHECK NEAR ADDRESS: INVALID OPCODE AT ADDRESS: NO COPROCESSOR AVAILABLE AT ADDRESS: DOUBLE FAULT EXCEPTION AT ADDRESS: NPX SEGMENT OVERRUN NEAR ADDRESS: INVALID TSS AT ADDRESS: SEGMENT NOT PRESENT AT ADDRESS: STACK FAULT AT ADDRESS: GENERAL PROTECTION AT ADDRESS: PAGE FAULT AT ADDRESS: FLOATING POINT ERROR NEAR ADDRESS: ALIGNMENT CHECK NEAR ADDRESS: AT ADDRESS or NEAR ADDRESS is output, depending on whether the EIP register contains the address of the triggering or of the next command after the exception interrupt. 74 Programming Manual, 07/2012, A5E

75 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. Programming Manual, 07/2012, A5E

76 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). 76 Programming Manual, 07/2012, A5E

77 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. Programming Manual, 07/2012, A5E

78 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. 78 Programming Manual, 07/2012, A5E

79 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 Programming Manual, 07/2012, A5E

80 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> <name> <status text> failed ID of the core at which the error has occurred Decoded SVC name, e.g. RmGetFlag One of the following text strings is inserted, depending on the system state at the call of the SVC exception handler. 1. from task: <name> id: 0xXX 2. during system startup 3. in monitor mode 4. in s-state 5. in i-state 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 :20:57, svc RmGetEntry from task: RUN id: 0x29 failed: 36 (Invalid ID) 80 Programming Manual, 07/2012, A5E

81 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 E_CLI_NOT_RESIDENT No resident task E_CLI_FILE_FORMAT Invalid file format E_CLI_DYNAMIC_MEM Out of dynamic memory E_CLI_INTERNAL_ERROR Internal error E_CLI_LTT_FULL Loaded task table is full E_CLI_CJT_FULL CLI job table is full E_CLI_CREATE_ERROR Error when creating a task E_CLI_START_ERROR Task start error E_CLI_DELTSK_ERROR Error when deleting a task E_CLI_LT_ACTIVE The specified loaded task is active E_CLI_JOB_ACTIVE The specified CLI job is computing E_CLI_FILE_NOT_FOUND File not found E_CLI_NOT_A_CLI_JOB Task is not a CLI job E_CLI_NOT_A_CRUN_JOB Task is not a CRUN task E_CLI_NOT_INLINE Not an Inline command E_CLI_SYNTAX_ERROR Syntax error E_CLI_ENVIRONMENT_FULL No memory available for new environment 0 0x8201 0x8202 0x8203 0x8204 0x8205 0x8206 0x8207 0x8208 0x8209 0x820A 0x820B 0x820C 0x820D 0x820E 0x820F 0x8210 0x8211 Programming Manual, 07/2012, A5E

82 Error codes and messages 4.4 CLI E_CLI_NO_COMMAND Command not available E_CLI_EOF End of file E_CLI_EXIT_STATUS Exit status (as return value of the EXIT command) E_CLI_CATALOG_FULL RMOS3 catalog is full E_CLI_CREATESEMA_ERROR Error when creating a semaphore E_CLI_REDIR_STDIN_FAIL Error when redirecting stdin E_CLI_REDIR_STDOUT_FAIL Error when redirecting stdout E_CLI_REDIR_STDERR_FAIL Error when redirecting stderr E_CLI_UNKNOWN_SWITCH Unknown switch E_CLI_TOO_MANY_PARAMS Too many parameters E_CLI_INVALID_FILENAME Invalid file name E_CLI_INVALID_LT_INDEX Invalid task index E_CLI_INVALID_JOB_INDEX Invalid CLI job number E_CLI_TOO_FEW_PARAMS Insufficient number of parameters E_CLI_FILE_READ_ERROR File read error E_CLI_FILE_WRITE_ERROR File write error E_CLI_COPY_TO_SELF Attempt to copy a file to itself E_CLI_UNEXPECTED_EOF Unexpected EOF reached E_CLI_PERMANENT_TASK Permanent CLI task E_CLI_NO_PROMPT Missing prompt definition E_CLI_JOB_ABORTED Job was aborted E_CLI_NOT_A_DEVICE Not a device name 0x8212 0x8213 0x8214 0x8215 0x8216 0x8217 0x8218 0x8219 0x821A 0x821B 0x821C 0x821D 0x821E 0x821F 0x8220 0x8221 0x8222 0x8223 0x8224 0x8225 0x8226 0x Programming Manual, 07/2012, A5E

83 Error codes and messages 4.4 CLI E_CLI_MKDIR_FAIL Creation of directory failed E_CLI_BATCH_FILE File is a batch file E_CLI_NOT_MOUNTED Volume not mounted E_CLI_INVALID_WILDCARD Invalid use of wildcards E_CLI_NOT_A_DIRECTORY Not a directory E_CLI_DIR_OPEN_FAIL Failed to open directory E_CLI_FILE_OPEN_FAIL Failed to open file E_CLI_FILE_CLOSE_FAIL Failed to close file E_CLI_SVC_ERROR SVC error E_CLI_DEV_READ_ERROR Error when reading from device E_CLI_DEV_WRITE_ERROR Error when writing to device E_CLI_IS_A_DIRECTORY File is a directory E_CLI_INLINE Inline CLI command E_CLI_COMPLETED CLI job is completed E_CLI_UNINITIALISED CLI job was not initialized E_CLI_OUT_OF_RANGE Index out of range E_CLI_NO_SPACE_FOR_NPX Setup of NPX context failed when creating the task E_CLI_NO_PARENT_JOB No parent job E_CLI_INVALID_VOL_NAME Invalid volume name E_CLI_MOUNTED Volume is mounted E_CLI_INVALID_DATE_TIME Invalid date or time format E_CLI_READ_ONLY File is read only 0x8228 0x8229 0x822A 0x822B 0x822C 0x822D 0x822E 0x822F 0x8230 0x8231 0x8232 0x8233 0x8234 0x8235 0x8236 0x8237 0x8238 0x8239 0x823A 0x823B 0x823C 0x823D Programming Manual, 07/2012, A5E

84 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. 84 Programming Manual, 07/2012, A5E

85 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. Programming Manual, 07/2012, A5E

86 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. 86 Programming Manual, 07/2012, A5E

87 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. Programming Manual, 07/2012, A5E

88 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. 88 Programming Manual, 07/2012, A5E

89 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. Programming Manual, 07/2012, A5E

90 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. 90 Programming Manual, 07/2012, A5E

91 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 RMOS H E_LD_FILE_OPEN_FAIL Cannot open file Program file could not be opened. It probably does not exist. 8111H E_LD_FILE_FORMAT Unknown file format The file has an unknown format. The format is identified based on the first byte or word of the file: STL: 1st word = 0206H PE: 1st 16 bit word = "M2" 1st 32 bit word of NEW EXE header = H, Magic number of optional header == H 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. Programming Manual, 07/2012, A5E

92 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 8153H E_LD_TOO_MANY_OBJECTS Too many objects Invalid descriptor Error when converting a segment address to a physical address. 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 92 Programming Manual, 07/2012, A5E

93 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. Programming Manual, 07/2012, A5E

94 Error codes and messages 4.10 LOADRM task loader 94 Programming Manual, 07/2012, A5E

95 5 5.1 Overview Programming with SVC RmIO The functions of the basic I/O system are programmed using SVC RmIO. The RmIO parameters specify the drivers to be activated, the function to execute, and so forth. The RmIO parameters that are identical for all driver calls (bit 7, 6 of Function, DeviceID, UnitID, FlagID, FlagMask, *pstate,*pparam), are defined at the SVC RmIO. This section provides a description of the properties for each driver, of the parameters of SVC RmIO, as well as of the respective basic structures that are relevant for driver configuration. Programming Manual, 07/2012, A5E

96 5.2 BYT driver 5.2 BYT driver 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. 96 Programming Manual, 07/2012, A5E

97 5.2 BYT driver 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 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. Programming Manual, 07/2012, A5E

98 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 Call R E S E R V E 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 1st Call RESERVE 00 RELEASE 01 READ WRITE XWRT ONE_XREAD WRT_XREAD WRT_READ SKIP_LINE FORM_FEED HSFS_XREAD HSFS_WRITE POLL_XBUFF CHECK_ABO CREATE_NEW 14 Multifunction 15 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 E W Multifunction - 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 98 Programming Manual, 07/2012, A5E

99 5.2 BYT driver 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. Programming Manual, 07/2012, A5E

100 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 RUBOUT_INPUT BACKSPACE_INPUT NEXT_HISTORY LAST_HISTORY INSERT_BLANK DELETE_CHAR ZAP_RIGHT_INPUT CURSOR_START CURSOR_END CURSOR_RIGHT CURSOR_LEFT CLEAR_SCREEN Terminate input without echo Delete last character entered Delete character left of the cursor position History mode: go forward History mode: go backward Insert blank at cursor position Delete character at cursor position Delete line characters on the right side Set cursor to the start of the entry Set cursor to the end of the entry Shift cursor right by one character Shift cursor left by one character 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 100 Programming Manual, 07/2012, A5E

101 5.2 BYT driver 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 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 Programming Manual, 07/2012, A5E

102 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 102 Programming Manual, 07/2012, A5E

103 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 Programming Manual, 07/2012, A5E

104 5.2 BYT driver 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. 104 Programming Manual, 07/2012, A5E

105 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.) Programming Manual, 07/2012, A5E

106 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. 106 Programming Manual, 07/2012, A5E

107 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. Programming Manual, 07/2012, A5E

108 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 Meaning 0 Read next ASCII character from keyboard. The character code is transferred to the AL register, while the scan code of the key is transferred to the AH register. If no character exists, the program waits until a character is available. Take this aspect into account when calling this function. 1 Set zero flag if the buffer is not cleared. ZF = 1 > no character. ZF = 0 > character available. 2 Fetch SHIFT status to AL register You can use subfunction 15 of the multifunction to close the internal input interface again. As soon as it is closed, it is not longer possible to fetch characters via this interface. 108 Programming Manual, 07/2012, A5E

109 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 Programming Manual, 07/2012, A5E

110 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 110 Programming Manual, 07/2012, A5E

111 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 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 01H 02H 03H 04H 05H 06H 07H 08H 09H 0AH 0BH 0CH 0DH 0EH 0FH Reserve unit (BYT_RESERVE) Release unit (BYT_RELEASE) Read (BYT_READ) Write (BYT_WRITE) Unconditional writing (BYT_XWRT) Read character in transparent mode (BYT_ONE_XREAD) Write and read in transparent mode (BYT_WRT_XREAD) Write and read (BYT_WRT_READ) Skip line (BYT_SKIP_LINE) Clear screen (BYT_FORM_FEED) Read character to buffer in transparent mode (BYT_HSFS_XREAD) Write character from buffer (BYT_HSFS_WRT) Read interim buffer in transparent mode (BYT_POLL_XBUF) Check input buffer for abort characters (BYT_CHECK_ABO) Redefine and initialize the unit (BYT_CREATE_NEW) Multifunction (only for EGA units) Programming Manual, 07/2012, A5E

112 5.2 BYT driver Printer b) Output device (e.g. line printer): 00H 01H 03H 08H 09H 0BH 0EH 0FH Reserve unit (BYT_RESERVE) Release unit (BYT_RELEASE) Write (BYT_WRITE) Line feed (BYT_SKIP_LINE) Form feed (BYT_FORM_FEED) Write character from buffer (BYT_HSFS_WRT) Redefine and initialize the unit (BYT_CREATE_NEW) Multifunction (only for EGA units) Keyboard c) Input device (e.g. keyboard): 00H 01H 05H 0AH 0CH 0DH 0EH 0FH Reserve unit (BYT_RESERVE) Release unit (BYT_RELEASE) Read character in transparent mode (BYT_ONE_XREAD) Read character to buffer in transparent mode (BYT_HSFS_XREAD) Read interim buffer in transparent mode (BYT_POLL_XBUF) Check input buffer for abort characters (BYT_CHECK_ABO) Redefine and initialize the unit (BYT_CREATE_NEW) 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. 112 Programming Manual, 07/2012, A5E

113 5.2 BYT driver RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: Function, bit 5 Function, bit 3..0 pstate pparam Cancel bit Function code of the selected driver function Status pointer that reports internal states of the driver. 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 Function 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 reserved EH Valid opcode 0FH 0FH Reserved if the EGA functions cannot be executed (by implementing EGADMY.OBJ) 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). Programming Manual, 07/2012, A5E

114 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 Opcode 00H 01H 02H 03H 04H 05H 06H 07H 08H 09H 0AH 0BH 0CH 0DH 0EH 0FH Configuration as I/O device (e.g. terminal) Meaning Reserve unit (BYT_RESERVE) Release unit (BYT_RELEASE) Read (BYT_READ) Write (BYT_WRITE) Unconditional writing (BYT_XWRT) Read character in transparent mode (BYT_ONE_XREAD) Write and read in transparent mode (BYT_WRT_XREAD) Write and read (BYT_WRT_READ) Skip line (BYT_SKIP_LINE) Clear screen (BYT_FORM_FEED) Read character to buffer in transparent mode (BYT_HSFS_XREAD) Write character from buffer (BYT_HSFS_WRT) Read interim buffer in transparent mode (BYT_POLL_XBUF) Check input buffer for abort characters (BYT_CHECK_ABO) Redefine and initialize the unit (BYT_CREATE_NEW) 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. 114 Programming Manual, 07/2012, A5E

115 5.2 BYT driver b) Output device (e.g. line printer): Table 5-5 Opcode 00H 01H 03H 08H 09H 0BH 0EH 0FH Configuration as output device (e.g. line printer) Meaning Reserve unit (BYT_RESERVE) Release unit (BYT_RELEASE) Write (BYT_WRITE) Line feed (BYT_SKIP_LINE) Form feed (BYT_FORM_FEED) Write character from buffer (BYT_HSFS_WRT) Redefine and initialize the unit (BYT_CREATE_NEW) Multifunction (only for EGA units) c) Input device (e.g. keyboard): Table 5-6 Opcode 00H 01H 05H 0AH 0CH 0DH 0EH 0FH Configuration as input device (e.g. keyboard): Meaning Reserve unit (BYT_RESERVE) Release unit (BYT_RELEASE) Read character in transparent mode (BYT_ONE_XREAD) Read character to buffer in transparent mode (BYT_HSFS_XREAD) Read interim buffer in transparent mode (BYT_POLL_XBUF) Check input buffer for abort characters (BYT_CHECK_ABO) Redefine and initialize the unit (BYT_CREATE_NEW) 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" 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. Programming Manual, 07/2012, A5E

116 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 0 00H 0000H H 1 00H 0000H H H 1 (FFH) 00H 0000H H 2 (FEH) 00H 0000H H 3 (FDH) H 4 (FCH) H 5 (FBH) H 6 (FAH) H 7 (F9H) H 8 (F8H) 00H 0000H H Meaning I/O request is queued. Busy processing the I/O request. I/O request successfully completed. I/O request rejected due to invalid parameterization Reserve/release operation was not executed, as the unit is already reserved/not reserved. I/O request terminated due to timeout BYTE: I/O request terminated by cancel function BYTE: I/O request aborted due to invalid status check I/O request terminated by External Change Interrupt at the SCC 8530 block I/O request terminated by Special Receive Interrupt at the SCC 8530 block BYTE: Polling request rejected (read interim buffer in transparent mode, BYT_POL_XBUF) due to missing buffer mode configuration. 116 Programming Manual, 07/2012, A5E

117 5.2 BYT driver Table 5-8 RmIO parameter pstate (continuation) Primary status byte Secondary status byte 2nd status word 3rd and 4th status word 9 (F7H) H 10 (F6H) 00H 0000H H Meaning BYTE: Input request in buffer mode terminated due to buffer overflow 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 ) 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 (or 0..15, if the EGA functions cannot be executed; function 15 is reserved!): Type Offset Description Note POINTER far 0 Offset/segment of the output buffer or input request text WORD int 6 Length of the output buffer or input request text POINTER far 10 Offset/segment of the input buffer or transformation table WORD int 16 Length of the input buffer, or timeout value 2 WORD int 20 Block status information 3 24 Total scope Programming Manual, 07/2012, A5E

118 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. 1 The drivers always use the same segment value to execute I/O operations, which means changes to the segment value are ignored in the case of offset overrun (FFFFH..0H). 2 I/O data has a maximum length of 64 K. Only the least significant 2 bytes of 4 bytes are used. 3 Reserved for the transfer of block-related status information upon completion of an I/O operation (UCD.STMODE). The least significant byte contains the status information read for the status check. The most significant byte is only set to the content of RR0 at the 8274 und 8530 blocks. The least significant byte contains RR1 (status register 0 or 1). The most significant 2 bytes of the status word are set to 0. 4 A description of the parameters for the corresponding parameter block is available in the description of subfunctions of the multifunction Opcodes of the BYT driver Reserve unit (BYT_RESERVE) Opcode: 00H BYT_RESERVE Parameter block length: 24 bytes This function reserves the unit specified in the RmIO (unit_id) exclusively for I/O requests of the calling task. I/O requests of other tasks are accepted, but not executed until the unit has been released. An exception are I/O requests with set preemptive bit. I/O requests to a reserved unit are processed in a fixed order: Calls with set preemptive bit in chronological order Calls of the task that has reserved the unit in chronological order Calls of other tasks in the order of priority after the unit has been released If a task attempts to once again reserve a unit that has not yet been released, an error message ( 2) is returned in the primary status byte. The previous reservation is retained. 118 Programming Manual, 07/2012, A5E

119 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)". Programming Manual, 07/2012, A5E

120 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 Release unit (BYT_RELEASE) Opcode: 01H BYT_RELEASE Parameter block: None This function revokes the reservation of the unit specified in RmIO (unit_id). I/O requests that were blocked due to the reserved state are now executed in the order of their priority. If the task attempts to release a unit it has not reserved, or which was already released, error code ( 2) is returned in the primary status byte. This is the case, for example, if the reservation was already revoked by timeout. If you set the preemptive bit along with opcode 01H (i.e. opcode 81H) at an RmIO, it is also possible to release a unit that was reserved by a different task. 120 Programming Manual, 07/2012, A5E

121 5.2 BYT driver Read (BYT_READ) Opcode: 02H BYT_READ Parameter block: 24 bytes, 20 bytes restricted This function transfers characters from an I/O device to a user-defined input buffer with echo mode. The length and address of the user buffer are transferred in the parameter block. The length of the input buffer corresponds to the maximum number of characters to be read. With zero user buffer length, the input request is terminated without having been processed and without error message. Parameter block for read request: Type Offset Description Note POINTER far 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 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 (0DH) LF (0AH) In contrast, input terminator character will not generate echo output or change the cursor position on the screen, but the character is also saved to the input buffer. Programming Manual, 07/2012, A5E

122 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. 122 Programming Manual, 07/2012, A5E

123 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 Write (BYT_WRITE) Opcode: 03H BYT_WRITE Parameter block: 24 bytes, 10 bytes restricted This function transfers characters from a user-defined output buffer to an I/O device. The length and address of the output buffer are transferred in the parameter block. The length of the output buffer corresponds to the maximum number of characters to be written. With zero output buffer length, the write request is terminated without actual processing or error message. Parameter block for write request: Type Offset Description Note POINTER far 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 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. Programming Manual, 07/2012, A5E

124 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 EQU 01BH ;ESCAPE CHARACTER X EQU 0FEH ;FILL CHARACTER STOP EQU 0FFH ;DELIMITER CR EQU 00DH ;CARRIAGE RETURN LF EQU 00AH ;LINE FEED IND EQU 000H ;INDEX FOR EXTENSION ;TABLE (ESCAPE_TABLE) ESCAPE_TABLE DB 'YEAR: 19',X,X,' MONTH: ',X,X,' ' DAY: ',X,X,STOP OUTPUT_TEXT DB 'DATE ',ESC,IND,'900812',CR,LF,0 TEXT_LENGTH DW 43 ; OUTPUT WITH OUTPUT REQUEST AND CORRESPONDING PARAMETER ; BLOCK ALLOCATION: 'DATE YEAR: 1990 MONTH: 08 DAY: 12' 124 Programming Manual, 07/2012, A5E

125 5.2 BYT driver Unconditional writing (BYT_XWRT) Opcode: 04H BYT_XWRT Parameter block: 24 bytes, 10 bytes restricted With the exception of the routine for handling extension tables, the parameter block corresponds to the write function (03H). An extension table is not provided for this function. In contrast to to the write function (03H), the function is handled correctly in duplex mode even if a non-transparent read system call with echo mode (02H) is pending. Type Offset Description Note POINTER far 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 1 Unrestricted interpretation Read character in transparent mode (BYT_ONE_XREAD) Opcode: 05H BYT_ONE_XREAD Parameter block: None This function reads a single character from the unit without echo output. Each character input or key function (exception: abort characters) are transferred along with their binary value to the secondary status byte and therefore terminates the input request. The second status word for the number of actually transferred bytes then contains the value 1. No input prompt text is output for this function, regardless of whether or not such output was specified in the reservation. All characters are transferred if the transparent mode was configured. Note See also section "Data flow of a character received (Page 101)" Write and read in transparent mode (BYT_WRT_XREAD) Opcode: 06H BYT_WRT_XREAD Parameter block: 24 bytes, 20 bytes restricted The BYT driver transfers characters from a user-defined output buffer to an I/O device and then expects input characters from this unit. The length and address of the I/O buffers are passed in the parameter block. Programming Manual, 07/2012, A5E

126 5.2 BYT driver 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 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 Write and read (BYT_WRT_READ) Opcode: 07H BYT_WRT_READ Parameter block: 24 bytes, 20 bytes restricted This function corresponds to a combination of write and read operation. First, the program executes the output operation, and secondly the input operation. Type Offset Description Note POINTER far 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 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. 126 Programming Manual, 07/2012, A5E

127 5.2 BYT driver Skip line (BYT_SKIP_LINE) Opcode: 08H BYT_SKIP_LINE Parameter block: 24 bytes, 10 bytes restricted This function executes a carriage return/line feed CR/LF on the output unit. The number of CR/LF operations is defined in the parameter block. No CR/LF is executed if the value equals zero. The Carriage Return (0DH) and Line Feed (0AH) characters are output for the CR/LF operation. With normal completion, the second status word contains twice the number of CR/LFs that were specified in the parameter block and executed (2 characters per feed). Type Offset Description Note POINTER far 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 1 Unrestricted interpretation Clear screen (BYT_FORM_FEED) Opcode: 09H BYT_FORM_FEED Parameter block: None This function executes a form feed on the output device, or clears the screen. The necessary control characters are obtained from the UCD block (UCD.TOPCHR). This application must be supported by the hardware of the output device. Note For EGA units: Provided they are unequal to 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 Read character to buffer in transparent mode (BYT_HSFS_XREAD) Opcode: 0AH BYT_HSFS_XREAD Parameter block: 24 bytes, 6 bytes restricted This function corresponds to the "read character in transparent mode" function, with the exception that the character that was read is not returned in the secondary status byte, but in the user buffer. Programming Manual, 07/2012, A5E

128 5.2 BYT driver The parameter block to initialize prior to the call has the following structure: Type Offset Description Note POINTER far 0 Address of the input buffer WORD int 6 reserved 1 POINTER far 10 reserved 1 WORD int 16 reserved 1 WORD int 20 Status information 1 1 Unrestricted interpretation Write character (BYT_HSFS_WRT) Opcode: 0BH BYT_HSFS_WRT Parameter block: 24 bytes, 6 bytes restricted This function transfer a single character to the output device (exception: An output terminator terminates the output request without actual output processing (terminal mode)). Type Offset Description Note POINTER far 0 Address of the output buffer WORD int 6 reserved 1 POINTER far 10 reserved 1 WORD int 16 reserved 1 WORD int 20 Status information 1 1 Unrestricted interpretation Read interim buffer in transparent mode (BYT_POLL_XBUF) Opcode: 0CH BYT_POLL_XBUF Parameter block: 24 bytes This function copies characters from the interim buffer of a unit to a user-defined input puffer. If the interim buffer does not contain a sufficient number of characters, or none at all, the call is terminated without waiting for a new character and without error message. If the interim buffer contains more characters, the remaining characters will be retained in the buffer. The actual number of characters read is written to the second status word. With zero input buffer length, the call is terminated without having been processed and without error message. If no buffer mode was configured, the primary status byte contains the error code (-8). 128 Programming Manual, 07/2012, A5E

129 5.2 BYT driver 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 1 Unrestricted interpretation Check input buffer for abort characters (BYT_CHECK_ABO) Opcode: 0DH BYT_CHECK_ABO Parameter block: 24 bytes This function checks whether the BYT driver has received the ABORT_INPUT character from an I/O device since the last function call. The number of abort characters received is ignored. The abort character is not saved to the user-defined input buffer or interim buffer but serves for function control only. Type Offset Description Note POINTER far 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 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. Programming Manual, 07/2012, A5E

130 5.2 BYT driver Redefine and initialize the unit (BYT_CREATE_NEW) Opcode: 0EH BYT_CREATE_NEW Parameter block: 20 bytes This function is used to re-initialize a unit assigned to the driver, or the controller of this unit, and/or to read the current operating parameters of the unit to a user buffer. Meaning of the parameter block: Type Offset Description Note POINTER far 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. 130 Programming Manual, 07/2012, A5E

131 5.2 BYT driver Multifunction (only for EGA units) In UCD.UCMODE, the multifunction offers only the following subfunctions for USART number 1000B (EGA adapter and IBM compatible keyboard): Opcode: 0FH Parameter block: 4 bytes for subfunctions 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 n.a. Subfunctions 0..14: A value is always returned in the variable at offset 2 in the parameter blocks of subfunctions Subfunctions 0..10: Write and read functions: All calls relate to the write page set for the unit. Programming Manual, 07/2012, A5E

132 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 (3), (4) insignificant UCD.TOPCHR, least significant byte Output 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 (3), (4) insignificant UCD.TOPCHR, least significant byte Output 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). 132 Programming Manual, 07/2012, A5E

133 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 (3), (4) insignificant UCD.TOPCHR, least significant byte Output (if successful) 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 Programming Manual, 07/2012, A5E

134 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 Input 6: Scroll screen down (0 = clear window) 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. 134 Programming Manual, 07/2012, A5E

135 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. Programming Manual, 07/2012, A5E

136 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 136 Programming Manual, 07/2012, A5E

137 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 Output (if successful) the keyboard is assigned to 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. Programming Manual, 07/2012, A5E

138 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. 138 Programming Manual, 07/2012, A5E

139 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 (3), (4) insignificant UCD.TOPCHR, least significant byte Output Programming Manual, 07/2012, A5E

140 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 Example: Coordinates of the bottom right corner of the screen: 18H:4FH. 6 (BYTE char) Color attribute for rows This attribute is assigned to all characters of a new row (for information on the color pallet, see "Configuration"). 7 (BYTE char) Color attribute for characters This attribute is assigned to all characters (for information on the color pallet, see "Configuration"). 8 (WORD short) Cursor mode 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 * ) * 2 = Write position selector The selector values are specified in the builder session 18 8 bytes SME emulation 140 Programming Manual, 07/2012, A5E

141 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 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 "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. Programming Manual, 07/2012, A5E

142 5.2 BYT driver 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 "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 FMAX Maximum function code for type II driver char 0CH RESERV 2 reserved bytes char 00H, 00H 1 This value is occupied during system configuration 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 "Unit Control Data table (UCD)" in the System Manual. Parameters Offset Type Description Note PID 0 char reserved INTNO 1 char Number of the interrupt vector for this unit INT_ADR 2 void FAR * Address of the interrupt handler routine (occupied internally) 1 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. 142 Programming Manual, 07/2012, A5E

143 5.2 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 Note UCMODE 10 short Unit Control Code PRTSEG 12 short USART segment 1 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 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 1 MODEXT 553 char Mode extension of the driver ICOUNT 54 short Number of init outputs 3 MOBYTE 56 short 1. Initialization output MOBYTE 254 short nth init output 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. 2 2 Programming Manual, 07/2012, A5E

144 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 USART ID: 10 UC 0000 = USART 8251A 0001 = PPI 8255A w/o Strobe 9 UC 0100 = SCC UC 0101 = PPI 8255A w/ Strobe 0110 = TIMER E19/E = 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 ID for use of a transformation table: 5 TO 00 = not used 01 = used for output routines 10 = used for input routines 11 = used for I/O routines 4 IP ID for unit type 3 OP 00 = I/O device (always specify this ID for EGA units!) 01 = output device 10 = input device 11 = reserved 2 ST USART status check 1 CT 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 0 MD ID for DIO or MMIO 0 = DIO 1 = MMIO (this setting is ignored for EGA units. All data is output to memory. The keyboard is addressed directly by means of the corresponding registers.) The extended modes of the BYTE driver are configured in the most significant byte of RECOVR! 144 Programming Manual, 07/2012, A5E

145 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: C0: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: C0: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: C0:07. Programming Manual, 07/2012, A5E

146 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 8255 with HW strobe DATA OUT CMD STS BITMASK (set and reset) DATA IN CMD STS DATA OUT CMD STS CMD STS 8250 DATA MODEM CTRL LINE CTRL INTR ENABLE The following points must be kept in mind: LINE STS 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: Most significant byte: Filter mask for selecting corresponding bits of the status information read 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. 146 Programming Manual, 07/2012, A5E

147 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). Programming Manual, 07/2012, A5E

148 5.2 BYT driver Bit Designation Meaning 15 UN Unit number 14 UN 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 Current write page (page 0... page 3) 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 Number of units (0... 3) 2 AU 1 DP Current display page (page 0 page 3) 0 DP 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 Programming Manual, 07/2012, A5E

149 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 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. Programming Manual, 07/2012, A5E

150 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 H (EAX register) BYTE char XSTATUS H (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 H (EBX register) BYTE char XSTATUS H (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. 150 Programming Manual, 07/2012, A5E

151 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 Reserved (0) 2 x 1 RQX XON/XOFF handling of expected characters 0 RWX Operating mode 0: no XON/XOFF protocol (standard mode) 1: XON/XOFF protocol (special 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. Programming Manual, 07/2012, A5E

152 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: 0 Value is output. 1 Value is read (certain controllers are initialized by reading registers). Bit 15: 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). 152 Programming Manual, 07/2012, A5E

153 5.2 BYT driver Bit Designation Meaning 7 BC Background color 6 BC 5 BC 4 BC 3 FC Foreground color 2 FC 1 FC 0 FC 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 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). Programming Manual, 07/2012, A5E

154 5.2 BYT driver Note For EGA units: Observe the information provided in chapter "EGA specific configuration (Page 155)" 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 154 Programming Manual, 07/2012, A5E

155 5.2 BYT driver 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 X_BYT_INT_SYS X_BYT_CTRL_ALT_DEL X_RESET_INT X_SYS_REQ_INT Table for EGA specific control characters Number of the interrupt vector Number of the interrupt vector Interrupt routine 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. Programming Manual, 07/2012, A5E

156 5.2 BYT driver 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 */ }; 156 Programming Manual, 07/2012, A5E

157 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) Programming Manual, 07/2012, A5E

158 5.2 BYT driver Figure 5-11 Character table from 0 to 255 (0H to FFH), part 1 Notes x1 = Blank (000H) x2 = Dot x3 = Inverse x2 x4 = Circle x5 = Inverse x4 x6 = One note x7 = Two notes x8 = Star x9 = Arrow right x10 = Arrow left x11 = Triangle x12 = Blank (020H) x13 = Open triangle 158 Programming Manual, 07/2012, A5E

159 5.2 BYT driver Figure 5-12 Character table from 0 to 255 (0H to FFH), part 2 Note: x14 = Blank (0FFH) 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). Programming Manual, 07/2012, A5E

160 5.3 CRT driver 5.3 CRT driver 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 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 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. 160 Programming Manual, 07/2012, A5E

161 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 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. Programming Manual, 07/2012, A5E

162 5.3 CRT driver 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 01H 02H 03H 04H 05H 06H 07H 08H 09H 0AH 0BH 0CH Reserve unit (CRT_RESERVE) Release unit (CRT_RELEASE) Read (CRT_READ) Write (CRT_WRITE) Write (CRT_WRITE) Read character in transparent mode (CRT_ONE_XREAD) Write and read in transparent mode (CRT_WRT_XREAD) Write and read (CRT_WRT_READ) Skip line (CRT_SKIP_LINE) Clear screen (CRT_FORM_FEED) Read character to buffer in transparent mode (CRT_HSFS_XREAD) Write character from buffer (CRT_HSFS_WRT) 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 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 pparam 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. 162 Programming Manual, 07/2012, A5E

163 5.3 CRT driver Function parameter This parameter sets the selected CRT driver functions (bit 0..3) and controls the sequence of the driver function. Bit Values Function 7 Preemptive bit 0 I/O request in the order of priority 1 Set I/O request to the start of the queue 6 Wait bit 1 Wait for completion of the I/O operation 0 No waiting 5 reserved 4 reserved H..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 01H 02H 03H 04H 05H 06H 07H 08H 09H 0AH 0BH 0CH Reserve unit (CRT_RESERVE) Release unit (CRT_RELEASE) Read (CRT_READ) Write (CRT_WRITE) Write (CRT_WRITE) Read character in transparent mode (CRT_ONE_XREAD) Write and read in transparent mode (CRT_WRT_XREAD) Write and read (CRT_WRT_READ) Skip line (CRT_SKIP_LINE) Clear screen (CRT_FORM_FEED) Read character to buffer in transparent mode (CRT_HSFS_XREAD) Write character from buffer (CRT_HSFS_WRT) 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. Programming Manual, 07/2012, A5E

164 5.3 CRT driver 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 H I/O request is queued. 1 00H 0000H H Busy processing the I/O request H I/O request successfully completed. 1 00H 0000H H I/O request rejected due to invalid parameterization 2 00H 0000H H Reserve/release operation was not executed, as the unit is already resevered/not reserved H I/O request terminated due to timeout H reserved H reserved H I/O request terminated by External Change Interrupt at the SCC 8530 block H 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. 164 Programming Manual, 07/2012, A5E

165 5.3 CRT driver Parameter pparam SVC RmIO uses parameter pparam to pass a pointer to a 20-byte field. This field must be initialized prior to the call, depending on the selected CRT driver function (e.g. read). The respective meaning of the bytes of the parameter block is explained in the description of CRT driver functions. Always set reserved parameters to zero. Type Offset Description Note POINTER far 0 0 Offset/segment of the output buffer or input request text 1 WORD int 6 6 Length of the output buffer or input request text POINTER far Offset/segment of the input buffer or transformation table 1 WORD int 16 Length of the input buffer or transformation table Total scope 1 The drivers always use the same segment value to execute I/O operations, which means that changes to the segment value are ignored in the case of offset overrun (FFFFH..0H) Opcodes of the CRT driver 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. Programming Manual, 07/2012, A5E

166 5.3 CRT driver Release unit (CRT_RELEASE) Opcode: 01H CRT_RELEASE Parameter block: None This function revokes the reservation of the unit specified in RmIO (unit_id). I/O requests that were blocked due to the reserved state are now executed in the order of their priority. If the task attempts to release a unit it has not reserved, or which was already released, error code ( 2) is returned in the primary status byte Read (CRT_READ) Opcode: 02H CRT_READ Parameter block: 20 bytes This function transfers characters from an I/O device to a user-defined input buffer with echo mode. The length and address of the user buffer are transferred in the parameter block. The length of the input buffer corresponds to the maximum number of characters to be read. With zero user buffer length, the input request is terminated without having been processed and without error message. The parameter block for read requests must have the following structure: Type Offset Description Note POINTER far 0 reserved WORD int 6 reserved POINTER far 10 Address of the input buffer WORD int 16 Length of the input buffer The characters entered on the keyboard (masked with 7FH) are saved to the user buffer and displayed as echo on the terminal. The CRT driver adds the value 40H to characters that cannot be mapped (input value less than 20H, or greater than 7FH), and the echo is output (masked with 7FH) along with the circumflex (^). Terminating the read operation The read operation is terminated at the following conditions: 1. Carriage return characters (CR, 0DH) 2. Input terminators (CTRL Z, 1AH) 3. Maximum buffer length reached On completion of a read request, the secondary status byte receives the last character read and the second status word receives the number of bytes actually read. The carriage return characters (CR), as well the line feed characters (LF) in line feed mode, are included in the count. CR and LF are saved to the input buffer, while the latter is only saved in line feed mode and if sufficient space is available in the input buffer. After CR, the following output appears on the screen: Carriage return Line feed (only in line feed mode) CR (0DH) LF (0AH) 166 Programming Manual, 07/2012, A5E

167 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: Delete key (DEL): CTRL X: The last character entered is cleared from the buffer and on the screen The last entry is cleared from the buffer (and screen). The RmIO remains open Write (CRT_WRITE) Opcode: 03H CRT_WRITE Parameter block: 20 bytes This function transfers characters from a user-defined output buffer to a terminal. The length and address of the output buffer are transferred in the parameter block. The length of the output buffer corresponds to the maximum number of characters to write. With zero output buffer length, the write request is terminated without having been processed and without error message. Parameter block for write request: Type Offset Description Note POINTER far 0 Address of the output buffer WORD int 6 Length of the output buffer POINTER far 10 reserved WORD int 16 reserved Terminating the write operation The write operation is terminated under the following conditions: 1. Null byte (WRITE_TERMINATOR) detected 2. The specified number of characters was output 3. Timeout expired On completion of the RmIO, the secondary status byte contains the last character output, while the second status word contains the number of bytes actually transferred Write (CRT_WRITE) Opcode: 04H CRT_WRITE Parameter block: 20 bytes This function is identical with opcode 03. Programming Manual, 07/2012, A5E

168 5.3 CRT driver Read character in transparent mode (CRT_ONE_XREAD) Opcode: 05H CRT_ONE_XREAD Parameter block: None This function reads a single character without echo output. Each character input or keyboard function, is transferred with its binary value to the secondary status byte and therefore terminates the input request. The second status word that indicates the number of actually transferred bytes will then contain the value Write and read in transparent mode (CRT_WRT_XREAD) Opcode: 06H CRT_WRT_XREAD Parameter block: 20 bytes The CRT driver transfers characters from a user-defined output bufer to an I/O device and then expects an input character from this unit. The length and address of the I/O buffers are transferred in the parameter block. Type Offset Description Note POINTER far 0 Address of the output buffer WORD int 6 Length of the output buffer POINTER far 10 Address of the input buffer WORD int 16 Length of the input buffer With zero output buffer length, the write operation is ignored and only the read operation is processed. No read operation is initiated at zero length of the input buffer. Character output is subject to the same conditions as for function 03. In contrast to function 02, the following restrictions must be taken into account for character input: Input characters do not generate echoes on the screen. Terminators and control characters have no further influence and are also transferred to the input buffer. The input operation is not terminated until the maximum length of the input buffer has been reached. The conclusion of the I/O request corresponds to that of function 02 in terms of the secondary status byte. The function is not terminated until the read call is completed. 168 Programming Manual, 07/2012, A5E

169 5.3 CRT driver Write and read (CRT_WRT_READ) Opcode: 07H CRT_WRT_READ Parameter block: 20 bytes This function corresponds to a combination of write and read operation. First, the program executes the output operation, and secondly the input operation. Type Offset Description Note POINTER far 0 Address of the output buffer WORD int 6 Length of the output buffer POINTER far 10 Address of the input buffer WORD int 16 Length of the input buffer With zero output buffer length, the write operation is ignored and only the read operation is processed. No read operation is initiated at zero length of the input buffer. The write operation is subject to the same conditions as for function 03. Reading corresponds to function 02. On completion of the I/O request, the secondary status byte contains the last character input, while the second status word contains the number of input bytes actually transferred Line feed/skip line (CRT_SKIP_LINE) Opcode: 08H CRT_SKIP_LINE Parameter block: 20 bytes This function executes a carriage return/line feed CR/LF on the output unit. The number of CR/LF operations is defined in the parameter block. No CR/LF is executed if the value equals zero. The Carriage Return (0DH) and Line Feed (0AH) characters are output for the CR/LF operation. With normal completion, the second status word contains twice the number of CR/LFs that were specified in the parameter block and executed (2 characters per feed). Type Offset Description Note POINTER far 0 reserved WORD int 6 Number of carriage returns/line feeds POINTER far 10 reserved WORD int 16 reserved Form feed/clear screen (CRT_FORM_FEED) Opcode: 09H CRT_FORM_FEED Parameter block: none This function executes a form feed on the output device, or clears the screen. The necessary control characters are obtained from the UCD block (UCD.TOPCHR). This application must be supported by the hardware of the output device. Programming Manual, 07/2012, A5E

170 5.3 CRT driver Read character in transparent mode (CRT_HSFS_XREAD) Opcode: 0AH CRT_HSFS_XREAD Parameter block: 20 bytes This function corresponds to function 05, with the exception that the character that was read is not returned in the secondary status byte, but in the user buffer. The parameter block to initialize prior to the call has the following structure: Type Offset Description Note POINTER far 0 Address of the input buffer WORD int 6 reserved POINTER far 10 reserved WORD int 16 reserved Write character (CRT_HSFS_WRITE) Opcode: 0BH CRT_HSFS_WRITE Parameter block: 20 bytes This function transfers a single character to the output unit. The parameter block to initialize prior to the call has the following structure: Type Offset Description Note POINTER far 0 Address of the output character WORD int 6 reserved POINTER far 10 reserved WORD int 16 reserved Redefine unit (CRT_CREATE_NEW) Opcode: 0CH CRT_CREATE_NEW Parameter block: 20 bytes This function is used to re-initialize a unit assigned to the driver, or the controller of this unit, and/or to read the current operating parameters of the unit to a user buffer. Meaning of the parameter block: Type Offset Description Note POINTER far 0 Address of the UCD buffer WORD int 6 reserved POINTER far 10 Address of the input buffer WORD int 16 Length of the input buffer 170 Programming Manual, 07/2012, A5E

171 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 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 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 (^) Programming Manual, 07/2012, A5E

172 5.3 CRT driver Configuration 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 "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 INIT Identification of shared controllers (0FFH if none) Entry point of the initialization routine in the driver char 0FFH 1 void NEAR * X_CRT_INIT SVC RIO SVC entry point for driver void X_CRT_SVC_BR NEAR * FLAGS Driver flags: char 03H Bit0=1: Parallel driver Bit1=1: Type II driver Bit2=0: Initialization in the boot sequence FMAX Maximum function code for type II driver char 0CH RESERV 2 reserved bytes char 00H, 00H 1 This value is occupied during system configuration 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 "Unit Control Data table (UCD)" in the System Manual. The configuration of the UCD blocks, except for the reserved parameters, is closely oriented on the BYT driver. The examples for the configuration can therefore be derived from the corresponding examples of the BYT driver. Parameters Offset Type Description Note PID 0 char ID of the processor that operates the unit INTNO 1 char Number of the interrupt vector for this unit INT_ADR 2 void FAR * Address of the interrupt handling routine (assigned internally) 1 UNS 8 short Task ID of the task started after an unexpected input (0FFFFH if none) PORT 10 Driver-specific data (120/246 bytes) 256 Total 1 See Interrupt routines of the CRT2 driver. (Page 177) 172 Programming Manual, 07/2012, A5E

173 5.3 CRT driver 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. Programming Manual, 07/2012, A5E

174 5.3 CRT driver UCMODE (Unit Control Code) Bit Designatio n Meaning 15 reserved LF 0 = CR without LF 1 = CR followed by LF 11 UC USART ID: 10 UC 0000 = USART 8251A 0001 = PPI 8255A w/o Strobe 9 UC 0010 = reserved 8 UC 0011 = reserved 0100 = SCC = PPI 8255A w/ Strobe 0110 = TIMER E19/E = reserved 1000 = reserved 1001 = UART = reserved 1011 = reserved 11XX = reserved 7 x reserved 6 x 5 x 4 x 3 x 2 x 1 x 0 MD ID for DIO or MMIO 0 = DIO (direct I/O) 1 = MMIO (Memory Mapped I/O) Comments on entering port addresses The table contains the controller-specific entries for the port addresses in the UCD table: Controllers PRTDAT PRTCMD PORT_2 PORT_3 PTRSTA 8530 DATA A/B CMD A/B CMD A CMD B 8251 DATA CMD STS 8255 with SW DATA OUT CMD STS BITMASK (set and DATA IN CMD STS strobe reset) 8255 with HW DATA OUT CMD STS CMD STS strobe 8250 DATA MODEM CTRL LINE CTRL INTR ENABLE LINE STS 174 Programming Manual, 07/2012, A5E

175 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. Programming Manual, 07/2012, A5E

176 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 EAX register char XSTATUS + 02: 00H char XSTATUS + 03: 00H char XSTATUS + 04: Start character char XSTATUS + 05: 00H EBX register char XSTATUS + 06: 00H char XSTATUS + 07: 00H The XSTATUS parameters are transferred at task start to the EAX and EBX registers of the processor. The task which is started due to an unexpected input can evaluate the start character by reading the start character in the EBX register and possibly start additional tasks. RECOVR (recovery time) The CRT2 driver uses this parameter internally to set a delay between two successive I/O errors. The waiting time (recovery time) to be maintained is specified in the description of the controller. The delay value depends on the processor used and on its clock frequency. MOBYTE (init output) This value corresponds to an init unit and is interpreted by the CRT2 driver as follows: Least significant byte: Most significant byte: Init byte or mode byte to be output. 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 Programming Manual, 07/2012, A5E

177 5.3 CRT driver 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 Stack requirements of the CRT2 driver RM3 S state 40 words I state 48 words DI state - Programming Manual, 07/2012, A5E

178 5.4 RAM disk driver 5.4 RAM disk driver 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 RAM_DRV.H RAM_3.SUB C source code Header file 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. 178 Programming Manual, 07/2012, A5E

179 5.4 RAM disk driver 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 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 Opcodes of the RAM DISK driver The RAM driver executes the following opcodes. 00H 01H 02H 03H 04H 05H 06H 07H 08H 09H 0AH 0BH 0CH 0DH 0EH 0FH Reserve RAM DISK Release RAM DISK Read logical block Write logical block Dummy operation Read logical blocks Write logical blocks reserved reserved reserved reserved reserved reserved reserved I/O control 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. Programming Manual, 07/2012, A5E

180 5.4 RAM disk driver 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 pparam Function code of the selected driver function Status pointer that reports internal states of the driver. 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 Function 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, 4 reserved H..06H Valid opcode 07H..0DH 0EH 0FH reserved Valid opcode reserved Opcode (bits 0 to 3) The RAM driver executes the following function codes. 00H 01H 02H 03H 04H 05H 06H 07H Reserve RAM DISK Release RAM DISK Read logical block Write logical block Dummy operation Read logical blocks Write logical blocks reserved 180 Programming Manual, 07/2012, A5E

181 5.4 RAM disk driver 08H 09H 0AH 0BH 0CH 0DH 0EH 0FH reserved reserved reserved reserved reserved reserved I/O control operation 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 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. Primary status byte Secondary status byte 2nd status word 3rd and 4th status word Meaning 0 00H 0000H H I/O request is queued. 1 00H 0000H H Busy processing the I/O request. 2 00H 0000H H I/O request successfully completed. 1 00H 0000H H I/O request rejected due to invalid parameterization 2 00H 0000H H Reserve/release operation was not executed, as the unit is already reserved/not reserved H 0000H H Configuration error 1 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. Programming Manual, 07/2012, A5E

182 5.4 RAM disk driver 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: 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 1 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 182 Programming Manual, 07/2012, A5E

183 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; Opcodes 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 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. Programming Manual, 07/2012, A5E

184 5.4 RAM disk driver 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 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 Dummy operation (04H) Opcode: 04H Parameter block: None This operation has no effect and is only implemented for reasons of RMOS3 compatibility. 184 Programming Manual, 07/2012, A5E

185 5.4 RAM disk driver 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 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. Programming Manual, 07/2012, A5E

186 5.4 RAM disk driver 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). 186 Programming Manual, 07/2012, A5E

187 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 WORD int reserved 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)") Configuration Driver control data (DCD) table Parameters Description Type Standard value UCD Address of the first UCD structure for int 1 this driver UNITS Number of units for this driver char 1 SHR Identification of shared controllers (0FFH char 0FFH 1 if none) INIT Entry point of the initialization routine in void NEAR * X_RAM_INIT the driver 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 FMAX Maximum function code for type II driver char 0EH RESERV 2 reserved bytes char 00H, 00H 1 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(). Programming Manual, 07/2012, A5E

188 5.4 RAM disk driver 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 "Unit Control Data table (UCD)". The general part of the UCD block has the following structure: General parameters in the UCD block 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 1 unexpected input PORT 10 Driver-specific data (120/246 bytes) 1 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. 188 Programming Manual, 07/2012, A5E

189 5.4 RAM disk driver RAM_MODE (access mode) Parameter RAM_MODE is defined as follows: Bit Designatio n Meaning 7 0 reserved (0) Phy Start address of the RAM DISK 0 = as selector/offset 1 = as absolute address 3 0 reserved (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. Programming Manual, 07/2012, A5E

190 5.5 DMA driver 5.5 DMA driver Properties 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 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 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. 190 Programming Manual, 07/2012, A5E

191 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 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 pparam 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 Function parameter This parameter sets the selected DMA driver functions (bit 0..3) and controls the sequence of the driver function. Bit Values Function 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 reserved H..05H Valid opcode 06H..0FH reserved Programming Manual, 07/2012, A5E

192 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 01H 02H 03H 04H 05H Reserve unit Release unit Read (from buffer to unit) Write (from unit to buffer) Cancel transmission (read or write) 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 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. Primary status byte Secondary status byte 2nd status word 3rd and 4th status word Meaning 0 00H 0000H H I/O request is queued. 1 00H 0000H H Busy processing the I/O request. 2 00H 0000H H I/O request successfully completed. 1 00H 0000H H I/O request rejected due to invalid parameterization 2 00H 0000H H Reserve/release operation was not executed, as the unit is already reserved/not reserved. 3 00H 0000H H I/O request terminated due to timeout H I/O request terminated by transfer abort function 1 Insignificant; undefined value 192 Programming Manual, 07/2012, A5E

193 5.5 DMA driver 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 Note 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 Opcodes Reserve unit (DMA_RESERVE) Opcode: Parameter block: 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 Note WORD short 0 reserved POINTER far 2 reserved WORD short 8 Timeout value (multiple of 256 ms) 1 WORD short 10 reserved WORD short 12 DMA transfer status POINTER far 14 reserved 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. Programming Manual, 07/2012, A5E

194 5.5 DMA driver 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 Read from memory (DMA_READ) Opcode: 02H Parameter block: 14 or 20 bytes This function transfers data from a user-defined buffer (RAM) to a DMA unit. Parameter block for read request: 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 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: 03H Parameter block: 14 or 20 bytes This function transfers data from a DMA unit to a user-defined buffer (RAM). Parameter block for write request: 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 1 Only taken into account if an extension of the DMA I/O parameter block is specified in UCD.CONTROL 194 Programming Manual, 07/2012, A5E

195 5.5 DMA driver 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: Type Offset Description Note 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 1 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 Programming Manual, 07/2012, A5E

196 5.5 DMA driver 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: ). 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 Programming Manual, 07/2012, A5E

197 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 (ADMA) and 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). Programming Manual, 07/2012, A5E

198 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 Meaning n 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) 198 Programming Manual, 07/2012, A5E

199 5.5 DMA driver 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); Programming Manual, 07/2012, A5E

200 5.6 FD0 driver 5.6 FD0 driver 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. 200 Programming Manual, 07/2012, A5E

201 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 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 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 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) Programming Manual, 07/2012, A5E

202 5.6 FD0 driver RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: Function, bit 5 Function, bit 3..0 pstate pparam Cancel bit 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 Function parameter This parameter selects the relevant FD0 driver operation (bits 0 to 3) and also controls the operational sequence. Bit Values Function 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 reserved H..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. 202 Programming Manual, 07/2012, A5E

203 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 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. Programming Manual, 07/2012, A5E

204 5.6 FD0 driver Primary status byte Secondary status byte 2nd status word 3rd and 4th status word Meaning 0 00H 0000H H I/O request is queued. 1 00H 0000H H Busy processing the I/O request. 2 00H 1) H I/O request successfully completed. 1 00H 0000H H I/O request rejected due to invalid parameterization 2 00H 0000H H Reserve/release operation was not executed, as the unit is already reserved/not reserved. 3 00H 0000H H I/O request terminated due to timeout 4 1) 1) H reserved 5 00H 7H 0000H 1) H I/O request aborted due to I/O error 6 00H 0000H H DMA error 7 1) 0000H H Pool/configuration error 8 1) 0000H H Delete/create error; unit not ready/available 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 Primary status byte POOL NOT RDY TIME RETRY 0 PROT 02 FD01 STS 0 (NEC status register 0) 03 FD01 STS 1 (NEC status register 1) Status information: Byte 00 Byte 01 Byte 02,03 Primary status byte Secondary status byte 2. status word FD0 unit status in secondary status byte: POOL NOTRDY TIME RETRY PROT Out of memory pool, or no additional buffer memory for read request Unit (drive) not ready Timeout Retry error Write protected floppy disk 204 Programming Manual, 07/2012, A5E

205 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 1 UNIT SELECT 1 0 UNIT SELECT 0 Indicates the head status during interrupt 1 If drive 1 is selected 1 If drive 0 is selected 2. status word (most significant byte) The status of NEC status register 1 is entered in this byte Bit Name Meaning 15 END OF CYLINDER 1 If the controller attempts to access a further sector after the last one. 14 reserved 13 DATA ERROR 1 On CRC error 12 OVERRUN 1 If the controller was not operated within the specified period. 11 reserved 10 NO DATA 1 If the controller could not find the sector. 9 NOT WRITABLE 8 MISSING ADDR. MARK 1 If the controller attempts to access a write protected floppy disk. 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 Programming Manual, 07/2012, A5E

206 5.6 FD0 driver FD_LBA FD_ADR FD_NB This parameter is used to specify the logical block address of the first block to address. The address of the read or write buffer for data transmission is entered in this parameter. 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 STRUC FD_LBA DD? FD_ADR %dp? FD_NB DW? FD_IOPB ENDS IOPB FD_IOPB <> Opcodes 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 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. 206 Programming Manual, 07/2012, A5E

207 5.6 FD0 driver 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 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 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 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. Programming Manual, 07/2012, A5E

208 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 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 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 Position to track 0 (FD2_RECA) Opcode: 09H Parameter required: none This operation resets the read/write head to track 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. 208 Programming Manual, 07/2012, A5E

209 5.6 FD0 driver 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 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 Programming Manual, 07/2012, A5E

210 5.6 FD0 driver Configuration 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 int 1 driver UNITS Number of units for this driver char 1 SHR Identification of shared controllers (0FFH if char 0FFH 1 none) INIT Entry point of the initialization routine in the void NEAR * X_FD0_INIT driver 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 FMAX Maximum function code for type II driver char 02H RESERV 2 reserved bytes char 00H, 00H 1 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 "Unit Control Data table (UCD)" in the System Manual. 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 1 (assigned internally) UNS 8 short Task ID of the task started after an 2 unexpected input (0FFFFH if none) PORT 10 Driver-specific data (120/246 bytes) 256 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 210 Programming Manual, 07/2012, A5E

211 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. Programming Manual, 07/2012, A5E

212 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 Sector length track 1..N 6 SLN 10 = 512 bytes/sector 5 SLO Sector length track 0 4 SLO 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 Selection of assigned 2 FD drives 0001 = drive 0 1 FD 0010 = drive 1 0 FD Meaning of the bits for control register 2: The most significant byte of SELECT must be initialized to zero for the FD0 driver. 212 Programming Manual, 07/2012, A5E

213 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) 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: ). Programming Manual, 07/2012, A5E

214 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: ). 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: ). Retry factor (MAX_RETRY) This parameter is used to define the maximum number of retries of an operation in error case. Least significant byte Most 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 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). 214 Programming Manual, 07/2012, A5E

215 5.6 FD0 driver Example: Sector numbering for 8 sectors/track with interleave factor: Interleave factor Sector sequence 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 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 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 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. Programming Manual, 07/2012, A5E

216 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 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 Stack requirements of the FD0 driver S state 30 words I state 34 words DI state Programming Manual, 07/2012, A5E

217 5.7 HD0 driver 5.7 HD0 driver 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. Programming Manual, 07/2012, A5E

218 5.7 HD0 driver 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 01H 02H 03H 04H 05H 06H 07H 08H 09H 0AH 0BH 0CH 0DH 0EH 0FH Reserve drive Release drive Read logical block Write logical block Format hard disk Read logical blocks Write logical blocks Reserved Reserved Reserved Read drive configuration parameters Delete drive configuration parameters Create drive configuration parameters Reserved Reserved 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 RmIO interface The parameters of SVC RmIO that are of importance for the description of driver properties are listed below: Function, bit 5 Function, bit 3..0 pstate pparam Cancel bit Function code of the selected driver function Status pointer that reports internal states of the driver. Points to a data block with other function-specific parameters. 218 Programming Manual, 07/2012, A5E

219 5.7 HD0 driver Function parameter This parameter selects the HD0 driver operation (bit 0 to 3) and controls the sequence of the driver function. Bit Values Function 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 (drive-oriented) 0 Valid data in interim buffer 1 Invalid data in interim buffer 4 reserved H..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 01H 02H 03H 04H 05H 06H 07H 08H 09H 0AH 0BH 0CH 0DH 0EH 0FH Reserve drive Release drive Read logical block Write logical block Format hard disk Read logical blocks Write logical blocks Reserved Reserved Reserved Read drive configuration parameters Delete drive configuration parameters Create drive configuration parameters Reserved Reserved Reserved Programming Manual, 07/2012, A5E

220 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 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. 2 HD0 status 1) HDC status 1) 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 3 HD0 Status 1) HDC Status 1) I/O request terminated due to timeout value 4 00H 0000H Reserved 5 HD0 Status 1) 6 HD0 Status 1) 7 HD0 Status 1) 8 HD0 Status 1) 1) See the following tables HDC Status 1) HDC Status 1) 0000H 0000H I/O request aborted due to I/O error I/O request aborted due to DMA error I/O request aborted due to pool/configuration error Delete/create error; unit not ready/available The 3rd and 4th status word are always 0000H. 220 Programming Manual, 07/2012, A5E

221 5.7 HD0 driver Status messages for all operations with the exception of "Reserve unit" or "Release unit": Byte Bit 00 Primary status byte POOL NOTRDY TIME RETRY HD status register 03 Operation status value 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 Programming Manual, 07/2012, A5E

222 5.7 HD0 driver Information for additional operations status (BIOS compatible) in 2nd status word (most significant byte): 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 HD01_ADR HD01_NB Dword for the logical block address The address (segment, offset) of the write/read buffer for data transmission is entered at this parameter This word specifies the number of logical blocks to transfer in succession. (This word is also used as timeout factor). 222 Programming Manual, 07/2012, A5E

223 5.7 HD0 driver Opcodes 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 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 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 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. Programming Manual, 07/2012, A5E

224 5.7 HD0 driver 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 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 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). 224 Programming Manual, 07/2012, A5E

225 5.7 HD0 driver 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) 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 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 Programming Manual, 07/2012, A5E

226 5.7 HD0 driver Configuration 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 INIT Identification of shared controllers (0FFH if none) Entry point of the initialization routine in the driver char 0FFH 1 void NEAR * X_HD0_INIT SVC RIO SVC entry point for driver void NEAR * X_HD0_SVC_BR FLAGS FMAX Driver flags: Bit0=1: Parallel driver Bit1=1: Type II driver Bit2=0: Initialization in the boot sequence Maximum function code for type II driver char char 2H 0DH RESERV 2 reserved bytes char 00H, 00H 1 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() 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 1 routine (assigned internally) UNS 8 short Task ID of the task started after 2 an unexpected input (0FFFFH if none) 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. 226 Programming Manual, 07/2012, A5E

227 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 "Unit Control Data table (UCD)" in the System Manual 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 48 WORD short Memory pool ID 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. Programming Manual, 07/2012, A5E

228 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 Meaning n 7 x Buffer mode Selection for block-oriented reading of a complete track to a drive-related memory buffer 6 0 reserved (0) x Drive selection 0 = drive 1 1 = drive 2 3 x Step rate time 2 x 0000 = 35 µs xxxx = 0.5 ms units 1 x 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). 228 Programming Manual, 07/2012, A5E

229 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: Value = 1 to 254: Value = 255: No drive parameter table available (HDPARAM=0); the values defined for drive-related parameters will be used. 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). 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. Programming Manual, 07/2012, A5E

230 5.7 HD0 driver Number of cylinders (MAX_CYL) This parameter defines the maximum number of cylinders of a HD (valid range of values: ). Number of sectors/track (MAX_SEC) This parameter defines the maximum number of sectors/track (valid range of values: ). 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: ). 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: ). Drive control value (CONTROL) This parameter defines specific HD operations and is coded as follows: Bit Designatio Meaning n 7 x Command repetition 6 x 00 = retry on error xx = no retries 5 0 Not evaluated x ID of number of heads > 8 0 = greater than or equal to 8 1 = greater than Not evaluated Programming Manual, 07/2012, A5E

231 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: Interleave sector Sector sequence 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 ). 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: ). 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. Programming Manual, 07/2012, A5E

232 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: ). 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: ). 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: ). 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. 232 Programming Manual, 07/2012, A5E

233 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 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 Stack requirements of the HD0 driver S state 30 words I state 34 words DI state 0 Programming Manual, 07/2012, A5E

234 5.8 COM driver 5.8 COM driver 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 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. 234 Programming Manual, 07/2012, A5E

235 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 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 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. Programming Manual, 07/2012, A5E

236 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) 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: 236 Programming Manual, 07/2012, A5E

237 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= Without BCC= 3964R protocol 3964 protocol Programming Manual, 07/2012, A5E

238 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 Example of signal sequences Figure 5-13 Receiving data 1) Only with 3964R protocol. BCC is omitted in the 3964 protocol and TQ begins after ETX (ETB). 238 Programming Manual, 07/2012, A5E

239 5.8 COM driver Figure 5-14 Sending data 1) Only with 3964R protocol. BCC is omitted in the 3964 protocol and TQ begins after ETX (ETB). Programming Manual, 07/2012, A5E

240 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. 240 Programming Manual, 07/2012, A5E

241 5.8 COM driver On completion of the read job, the slave restarts and executes the suspended write job 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: 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 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 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 01H 02H 03H 04H Reserve unit (C64_RESERVE) Release unit (C64_RELEASE) Read (C64_READ) Write (C64_WRITE) 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. Programming Manual, 07/2012, A5E

242 5.8 COM driver 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 pparam Function code of the selected driver function Status pointer that reports internal states of the driver. Points to a data block with other function-specific parameters Function parameter This parameter sets the selected COM driver functions (bits 0 to 3) and controls the sequence of the driver function. Bit Values Function 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 reserved 4 reserved H..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 01H 02H 03H 04H Reserve unit (C64_RESERVE) Release unit (C64_RELEASE) Read (C64_READ) Write (C64_WRITE) 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. 242 Programming Manual, 07/2012, A5E

243 5.8 COM driver 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 Primary status byte Secondary status byte 2nd status word 3rd and 4th status word Meaning 0 00H 0000H H I/O request is queued. 1 00H 0000H H Busy processing the I/O request H I/O request successfully completed. 1 00H 0000H H I/O request rejected due to invalid parameterization 2 00H 0000H H Reserve/release operation was not executed, as the unit is already reserved/not reserved H I/O request terminated due to timeout H reserved H reserved H I/O request terminated by External Change Interrupt at the SCC 8530 block H I/O request terminated by Special Receive Interrupt at the SCC 8530 block H 0000H H H mismatch of the BBC character and the calculated value Programming Manual, 07/2012, A5E

244 5.8 COM driver Primary status byte Secondary status byte 2nd status word 3rd and 4th status word Meaning 9 00H 0000H H Receive buffer overflow 10 00H 0000H H Initiation conflict H Protocol error: Received invalid control character H TQ time error H 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 1 buffer 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 RR Programming Manual, 07/2012, A5E

245 5.8 COM driver Opcodes 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 Note 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 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. Programming Manual, 07/2012, A5E

246 5.8 COM driver Release unit (C64_RELEASE) Opcode: 01H C64_RELEASE Parameter block: None This function revokes the reservation of the unit specified in RmIO (unit_id). I/O requests that were blocked due to the reserved state are now executed in the order of their priority. If the task attempts to release a unit it has not reserved, or which was already released, error code ( 2) is returned in the primary status byte. This is the case, for example, if the reservation was already revoked by timeout Read (C64_READ) Opcode: 02H C64_READ Parameter block: 24 bytes 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 Programming Manual, 07/2012, A5E

247 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 Write (C64_WRITE) Opcode: 03H C64_WRITE Parameter block: 24 bytes 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: Type Offset Description Note POINTER far 0 Address of the output buffer WORD int 6 Length of the output buffer POINTER far 10 reserved WORD int 16 reserved WORD int 20 Controller status information Redefine unit (C64_CREATE_NEW) Opcode: 0CH C64_CREATE_NEW Parameter block: 20 bytes This function is used to re-initialize a unit assigned to the driver, or the controller of this unit, and/or to read the current operating parameters of the unit to a user buffer. Programming Manual, 07/2012, A5E

248 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 Configuration 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 "Driver Control Data (DCD)". Parameters Description Type Standard value UCD Address of the first UCD structure for this int 1 driver UNITS Number of units for this driver char SHR Identification of shared controllers (0FFH if char 0FFH none) INIT Entry point of the initialization routine in void NEAR * X_3964_INIT the driver 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 FMAX Maximum function code for type II driver char 00H RESERV 2 reserved bytes char 00H, 00H 1 This value is occupied during the system configuration. 248 Programming Manual, 07/2012, A5E

249 5.8 COM driver 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)". 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) 1 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 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 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 Programming Manual, 07/2012, A5E

250 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 USART ID: 10 UC 0000 = USART 8251A 0100 = SCC UC 1001 = UART UC all others are reserved 7 x reserved 6 x reserved 5 x 4 SW USART status enable: 3 SR 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 2 ST USART status check 1 CT 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 0 MD 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: C0: Programming Manual, 07/2012, A5E

251 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: C0: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: C0: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 CMD A/B CMD A CMD B (configurable) 1) (configurable) 1) 8251 DATA CMD STS 8250 DATA MODEM CTRL LINE CTRL INTR ENABLE LINE STS 1) The "configurable" add-on means that the port addresses of channel A or B must be used, depending on the configured device. 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 Most significant byte Filter mask for selecting corresponding bits of the status information read Comparison mask for filtered status information Programming Manual, 07/2012, A5E

252 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. 252 Programming Manual, 07/2012, A5E

253 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 ÜB 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). Programming Manual, 07/2012, A5E

254 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 Most significant byte Bits 8 to 13 Init byte or mode byte to be output. 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 0 Value is output. 1 Value is read (certain controllers are initialized by reading registers). Bit 15 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 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). 254 Programming Manual, 07/2012, A5E

255 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 Stack requirements of the COM driver S state 42 words I state 54 words DI state 0 Programming Manual, 07/2012, A5E

256 5.9 SRAM driver 5.9 SRAM driver 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 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. 256 Programming Manual, 07/2012, A5E

257 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 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 pparam Function code of the selected driver function Status pointer that reports internal states of the driver. Points to a data block with other function-specific parameters. Programming Manual, 07/2012, A5E