AN INTRODUCTION TO PROGRAMMING THE DIGITAL EQUIPMENT CORP. RAINBOW PERSONAL COMPUTER ADDRESSING IBM PC COMPATIBILITY Table of Contents 1. Console interface 2. Keyboard interface 3. Disk Interface 4. Communications Interface 1.0 Console Interface 1.1 Generic MSDOS Calls (INT 21) 1.1.1 Function 2 (Display Character) 1.1.2 Function 9 (Display String) NOTE These generic calls work the same in both systems. 1.2 Generic MSDOS Calls with ANSI With the IBM PC you must load as part of the system the ANSI Escape Sequence driver. In the DEC Rainbow this is not required. IBM Rainbow Cursor functions: * Cursor Position ESC[#;#H same * Cursor Up ESC[#A same * Cursor Down ESC[#B same * cursor Forward ESC[#C same * Cursor Backward ESC[#D same * Hor & Vert Pos ESC[#;#f same * Device Status ESC[6n ESC[5n * Cursor Position Report ESC[#;#R same * Save Cursor position ESC[s ESC[7 * Restore Cursor Position ESC[u ESC[8 * Erase Display ESC[2J same * Erase to end of line ESC[k same Character attributes: * Normal white on black ESC[0m same * Bold on ESC[1 same * Underscore ESC[4 same * Blink ESC[5 same * Reverse Video ESC[7 same 1.3 Direct ROM Calls 1.3.1 IBM ROM Calls (INT 10) * Setting of mode * Set Cursor type * Set Cursor Position * Read Cursor Position * Select Active display page * Scroll active page up * Scroll acitve page down * Read attribute and Char at present cursor position * Write attribute and Char at present cursor position * Write char at present position 1.3.2 Rainbow ROM Calls (INT 40) * Write char at present position * disable/enable cursor * Send data to screen 1.0 Console Interface * Set Mode (IBM) * 40x25 black & white * 80x25 black & white Although the Rainbow does not have a ROM system call that is equivalent to this call, The operations that are available here can be accomplished with Ansi Escape Sequences. ESC#5 - 80 x 24 ESC#6 - 40 x 24 * Set/Read Cursor postion Once again The Rainbow does not have a ROM system call that is equivalent to this call. These features are available with ANSI Escape sequences. In the following examples, '#' refers to a numeric value representing row and column postition. ESC[#;#H Set Cursor ESC[#;#R Read Cursor position * Paging The IBM PC allows "paging" of video memory. The Rainbow does not support a paging scheme for the video. If paging is required, the user must write their own support routine(s). 1.0 Console Interface * Read Attribute & Character This is not supported by the Rainbow. A routine can be written to read the cursor position, calculate the memory location, then return the character and attribute set. * Write Char at present position IBM Rainbow Function AH = 10 DI = 1 Character Al AL Page BH N/A # Repeat Char CX N/A * Write Char & Attribute Although the Rainbow does not have an exact equivalent, it does provide a more powerful routine in that a single system call can write multiple characters/attributes. * Ranbow Fast Access to Video Memory via ROM (INT 40) DI = 14 AX = Transfer Type 0 = Character & Attribute 1 = Attribute only 2 Character only BL = Line number 1-24 BH = Column number 1-132 CX = Number of char/Attr to transfer. DX = Start address of Attributes SI = Start address of Characters BP = Segment code Memory Map For Video Rainbow EE000 to EEFFF Character Ram 4k EF000 to EFFFF Attribute RAM 4k IBM B0000 to B3FFF Character/Attribute RAM 16k Even Bytes are Character RAM Odd Bytes are Attribute RAM * Rainbow Video Memory Map - RAM Addresses Direct video memory access routines start by issuing escape sequence ESC[?3l with a generic INT 21H call. After this escape sequence is received the video memory will appear as follows for an 80 column display; the addresses are for the first line of the display: EE00:13 - EE00:62 (80 characters) 63 Termination Char (FF) 64-65 Address of next line Subsequent line addresses begin at the addresses in the following table: LINE 2 99H LINE 3 120H LINE 4 1A7H LINE 5 22EH LINE 6 2B5H LINE 7 33CH LINE 8 3C3H LINE 9 44AH LINE 10 4D1H LINE 11 558H LINE 12 5CFH LINE 13 666H LINE 14 6CDH LINE 15 774H LINE 16 7CBH LINE 17 882H LINE 18 8C9H LINE 19 990H LINE 20 9C7H LINE 21 AAEH LINE 22 AC5H LINE 23 BBCH LINE 24 BC3H CHARACTER ATTRIBUTES IBM RAINBOW REVERSE VIDEO YES YES BLINK YES YES UNDERSCORE YES YES BOLD YES YES IBM Attribute Byte Bit Mask 7 6 5 4 3 2 1 0 blink r g b intensity r g b \_____background_____/ \_____Foreground___/ background forground function r g b r g b 0 0 0 0 0 0 non display 0 0 0 0 0 1 underline 0 0 0 1 1 1 white char 1 1 1 0 0 0 reverse video Rainbow Attribute Byte Bit Mask Bit 0 = Reverse Video 0 = normal 1 = reverse video Bit 1 = Bold 0 = bold 1 = not bold Bit 2 = Blink 0 = blink 1 = no blink Bit 3 = Underscore 0 = underscore 1 = no underscore 2.0 Keyboard Interface * Generic MSDOS calls (INT 21H) * Function 1 (Read Keyboard & Echo) * Function 6 (Direct Keyboard I/O) * Function 7 (Direct keyboard input) * Function 8 (Read Keyboard) * Function 10 (Buffer keyboard input) * Function 11 (Check Keyboard Input) * Function 12 (Flush Buffer, Read keyboard) Note that these generic calls work the same in both IBM and Rainbow systems. * DIRECT ROM CALLS * IBM ROM Calls (INT 16) * Keyboard Input (AH=0, character returned in AL) * Keyboard Status (AH=1, Z-flag set = no character, character in AX) (Note that this allows non-destructive read!) * Return the current shift status * Rainbow ROM Calls (INT 40) * Keyboard Input (DI=2, character returned in AL) * Keyboard Status (DI=4, CL=0 no char / CL=FFH char) * Level 1 Keyboard Input ("raw" key-code) IBM shift key status The Shift status is the second charter of a keyboard sequence. Function keys and other keys will generate two byte inputs. The Rainbow generates an Escape Sequence when special keys (e.g. keypad) and function keys are typed. These Escape Sequences must then be parsed by the application itself. 3.0 Disk Interface * Generic MSDOS Calls All Generic Disk calls are eqivalent in the two systems. * Direct Hardware/Firmware/BIOS Calls * IBM ROM Calls (INT 13) * Reset Disk System * Read Status * Read Disk Sector * Write Disk Sector * Verify Disk Sector * Format Disk * Rainbow Floppy Disk Calls (INT 65) & Wini Calls (IOCTL 44) * Read Sector * Write Sector * Write & verify * Format * Media check * Verify media (bad block check) * MS-DOS Floppy Disk (RX50) I/O Control Functions INT 65H function = 0 Read = 1 Write = 2 Write / Verify = 3 Format = 4 Check Media Type Returned in 1st byte of Data Buffer: 0 = RX50 10-sector 1 = IBM 8-sector 2 = IBM 9-sector = 5 "Verify" Media (Bad Block Check) Function Packet Address in DS:BX register pair Packet Contents - byte = 0 Command code = 1 Drive (high nybble) = 2 Sector # = 3 Physical Drive = 4-5 Track # = 6-7 # of sectors = 8-9 Data Buffer Offset = A-B Data Buffer Segment * MS-DOS Winchester Disk I/O Control Functions To issue a I/O Control for Devices, Winchester (Function 44H): AH = 44H AL = function code; must = 4 or 5 BL = Drive (0 = Default, 1 = A, 2 = B, etc.) (Drive E, F, G, H are for Winchester) DS:DX = Block pointer BLOCK+0 DB Function code 0 - Read sector 1 - Write sector 2 - Write sector with verify 3 - Format track 4 - Media check 5 - Verify disk BLOCK+1 DB MS-DOS drive code or FF if physical unit (0 = drive A, 1 = B, etc. **) BLOCK+2 DB Sector number BLOCK+3 DB Unit number in high nybble Head number in low nybble Ignored if drive code .NE. FF BLOCK+4 DW Track number BLOCK+6 DW Sector count BLOCK+8 DW Offset of user buffer BLOCK+10 DW Segment of user buffer BLOCK+12 DW Returned data: Error code returned by driver, else 00 if successfully. Note#1: Carry set on return if error, return status in AL. Note #2: DS, BX & ES preserved accross call NOTE #1: Drive code in BL is different from Drive code in BLOCK+1. The Drive code in BL is to direct the MS-DOS BDOS to the appropriate disk driver. Drive code in BLOCK+1 is the actually drive code which will be used. NOTE #2: Logical operation (if drive code not equal to 0FFH) 1. first track number is offset to their partition 2. first sector number will be converted in skew table 3. multi-sector read/write use skew table 4. items 2 and 3 are not applicable to the first 2 tracks on each partition. i.e. first 2 tracks are not skewed Physical operation (if drive code is equal to 0FFH) 1. 2. first track/sector number is the physical number 3. 4. no skew table to the multi-sector read/write 4.0 MS-DOS Communication IOCTL interface Communication ports IOCTL Function 44H - register contents: On entry: AH = function request number, 44H AL = function code, either 2 or 3 will do BX = handle, 3 for AUX, 4 for PRN, AUX2 has to be "opened" by MS-DOS to get next available handle DS:DX = packet address CX = not used On return: Returned data are in packet format - the general format of this IOCTL packet is: label offset description --------------------------------------------------------------------- FUNCTION - BYTE 0 : function number FUNC_RETC - BYTE 1 : function return code = FF if sucessful, otherwise = 0 CHARACTER - BYTE 2 : character input or output CHAR_STAT - BYTE 3 : character status BUFFER - BYTE 4 to BYTE n : block buffer NOTE: Although IOCTL function is performed through each device, user still HAS TO supply the device number in the (BUFFER) where it is required. * DESCRIPTION OF EACH FUNCTION FUNCTION 0 - PROGRAM DEVICE FUNCTION: The device indicated by the Comm control block will be reprogrammed to the values specified in the CCB. ENTRY CONDITION: (FUNCTION) = 0 (BUFFER) = CCB data EXIT CONDITION: (FUNC_RETC) = FF, all functions programmed sucessfully. (FUNC_RETC) = 00 not all functions programmed sucessfully. The fields that cannot be programmed in the control block are marked with high order bit set. NOTE: This has no affect on receiver enabled or disabled status. FUNCTION 1 - PROGRAM DEVICE TO DEFAULT SETTINGS FUNCTION: The device will be reprogrammed to the default values as specified in NVM. The optional comm port will take the same values as the comm port. The state of the receiver will be enabled. ENTRY CONDITIONS: (FUNCTION) = 1 EXIT CONDITIONS : none FUNCTION 2 - SET DEVICE TO USE DEFAULT BUFFER FUNCTION: The device will be reprogrammed to the use the default buffer. This must be done before program termination. ENTRY CONDITIONS: (FUNCTION) = 2 EXIT CONDITIONS : none FUNCTION 3 - READ DEVICE SETUP FUNCTION: Information on the state of the device (how it is programmed) is passed back in the form of a Comm Control Block. The device number must be filled in by the application prior to this call to indicate which device is being asked for. ENTRY CONDITION: (FUNCTION) = 3 (BUFFER) = CCB data EXIT CONDITION: (FUNC_RETC) = 0 illegal device number, or device not installed. FUNCTION 4 - ENABLE RECEIVER FUNCTION: All input characters received will be placed in a circular buffer. In case of overruns, a hex FF character will be stored in the buffer. Each character will be stored with its status. ENTRY CONDITIONS: (FUNCTION) = 4 EXIT CONDITIONS : none FUNCTION 5 - DISABLE RECEIVER FUNCTION: All received characters will be ignored. ENTRY CONDITIONS: (FUNCTION) = 5 EXIT CONDITIONS : none FUNCTION 6 - READ INPUT STATUS FUNCTION: Read the status of the receive buffer. ENTRY CONDITIONS: (FUNCTION) = 6 EXIT CONDITIONS : (FUNC_RETC) = FF, character available (FUNC_RETC) = 0 , character not available FUNCTION 7 - READ INPUT CHARACTER, RETURN IF NONE AVAILABLE FUNCTION: Read the next character from the circular buffer. If none available then return to the caller. ENTRY CONDITIONS: (FUNCTION) = 7 EXIT CONDITIONS : (FUNC_RETC) = FF character available (FUNC_RETC) = 0 character not available (CHARACTER) = character, if available. (CHAR_STAT) = character status FUNCTION 8 - GET CHARACTER, RETURN WHEN AVAILABLE FUNCTION: Read the next character from the circular buffer. If none available then wait till one is available. ENTRY CONDITIONS: (FUNCTION) = 8 EXIT CONDITIONS : (CHARACTER) = character (CHAR_STAT) = status of character FUNCTION 9 - READ OUTPUT STATUS FUNCTION: Read status of the transmitter ENTRY CONDITIONS: (FUNCTION) = 9 EXIT CONDITIONS : (FUNC_RETC) = FF tranmitter ready (FUNC_RETC) = 0 transmitter not ready NOTE : If auto xon/xoff is active, this state of the output status can change in between 2 function calls !!! FUNCTION 10 - WRITE CHARACTER, RETURN IF UNABLE TO FUNCTION: Put the character in the transmitter, if unable then return to caller with appropriate error. ENTRY CONDITIONS: (FUNCTION) = 10 (CHARACTER) = character EXIT CONDITIONS : (FUNC_RETC) = FF transmit sucessful (FUNC_RETC) = 0 unable to transmit NOTE: if auto XON/XOFF enabled, XON and XOFF characters will be monitored for proper handling of xon/xoff by the drivers. FUNCTION 11 - PUT CHARACTER, RETURN WHEN SUCESSFUL FUNCTION: Put character into the transmit buffer, do not return till character is accepted. ENTRY CONDITIONS: (FUNCTION) = 11 (CHARACTER) = character EXIT CONDITIONS : none NOTE: if auto XON/XOFF enabled, XON and XOFF characters will be monitored for proper handling of xon/xoff by the drivers. FUNCTION 12 - TRANSMIT CHARACTER IMMEDIATELY FUNCTION: Put character into the transmit buffer immediately, ahead of other characters in the queue if necessary. This will ignore the state of the modem signals, that is if limited modem control is used, it will be ineffective for this character, and the characters ahead of it in the buffer. ENTRY CONDITIONS: (FUNCTION) = 12 (CHARACTER) = character EXIT CONDITIONS : none NOTE: if auto XON/XOFF enabled, XON and XOFF characters will be monitored for proper handling of xon/xoff by the drivers. FUNCTION 13 - READ MODEM SIGNALS FUNCTION: Get the incoming modem signals and the state of the transmit/receive flags. ENTRY CONDITIONS: (FUNCTION) = 13 EXIT CONDITIONS : (CHARACTER) = bit0 set RI on bit1 set SRLSD (or SPDI, bell 212A speed indicator) bit2 set DSR bit3 set CTS bit4 set RLSD bit5, bit6, undefined. bit7 if set, modem signals cannot be read (CHAR_STAT) = bit0 set Transmitter empty bit1 to bit4 undefined bit5 set receiver disabled bit6 set xoff received bit7 set xoff transmitted by application FUNCTION 14 - SET/CLEAR MODEM SIGNALS FUNCTION: The state of the outgoing modem signals are changed to the desired mask value. Note that this also clears unmasked signals. ENTRY CONDITIONS: (FUNCTION) = 14 (CHARACTER) = modem signal mask bit0 set SP set bit1 set SRTS set bit2 set DTR set bit3 set RTS set bit4 to bit7 ignored EXIT CONDITIONS: (FUNC_RETC) = 0 modem signals cannot be set (FUNC_RETC) = FF modem signals set FUNCTION 15 - TRANSMIT BREAK FUNCTION: The transmit data line will be latched to a space condition until "cease transmission of break" is requested. Note that it is up to the application program to ensure (if appropriate) the transmitter is empty. Note also that the duration of the space condition is completely up to the application program. ENTRY CONDITIONS: (FUNCTION) = 15 EXIT CONDITIONS : none FUNCTION 16 - CEASE TRANSMISSION OF BREAK FUNCTION: The transmit data line will be returned to a marking condition from the previous "transmit break" command. ENTRY CONDITIONS: (FUNCTION) = 16 EXIT CONDITIONS : none FUNCTION 17 - RECEIVE CHARACTER INTERRUPT FUNCTION: This is used so that a subroutine can be called at the end of each receive character interrupt. The call is made via a far call, and a far return has to be executed at the end. The routine is called when the interrupt is serviced and is enabled again. If a second in- terrupt occurs before this one is com- pleted (application returns) it will not be called the second time. ENTRY CONDITIONS: (FUNCTION) = 17 (BUFFER) = 5-byte buffer, first byte containing device number, and the remaining 4 has the offset and the segment of the routine to be called. EXIT CONDITIONS : (FUNC_RETC) = 0 invalid device or not installed = FF sucessful FUNCTION 18 - CANCEL RECEIVE CHARACTER INTERRUPT FUNCTION: This will cancel any previous function call 17 ENTRY CONDITIONS: (FUNCTION) = 18 EXIT CONDITIONS : none FUNCTION 19 - TRANSMIT BUFFER BECOMING EMPTY INTERRUPT FUNCTION: This is used so that an application subroutine can be called when the transmit buffer empty interrupt occurs. The call is made via a far call, and a far return has to be executed at the end. ENTRY CONDITIONS: (FUNCTION) = 19 (BUFFER) = 5-byte data area, containing device number followed by a double word containing address of the routine EXIT CONDITIONS : (FUNC_RETC) = 0 illegal device or not installed = FF sucessfully canceled. FUNCTION 20 - CANCEL TRANSMIT BUFFER BECOMING EMPTY INTERRUPT FUNCTION: This is used to cancel any previous function 19 call. ENTRY CONDITIONS: (FUNCTION) = 20 EXIT CONDITIONS : none FUNCTION 21 - EXTERNAL STATUS CHANGE INTERRUPT FUNCTION: This is used so that an application subroutine can be called when the external status change interrupt occurs. The call is made via a far call, and a far return has to be executed at the end. ENTRY CONDITIONS: (FUNCTION) = 21 (BUFFER) = 5-byte data area, containing device number followed by a double word containing address of the routine EXIT CONDITIONS : (FUNC_RETC) = 0 illegal device or not installed = FF sucessfully canceled. FUNCTION 22 - CANCEL EXTERNAL STATUS CHANGE INTERRUPT FUNCTION: This is used to cancel any previous function 21 call. ENTRY CONDITIONS: (FUNCTION) = 22 EXIT CONDITIONS : none FUNCTION 23 - PROGRAM DEVICE INTERRUPT VECTORS FUNCTION: This routine is used to re-define the interrupt service routine for a given device. When an interrupt occurs for this device, the application service routine will be called instead of the normally defined interrupt service routine. ENTRY CONDITIONS: (FUNCTION) = 23 (BUFFER) = ISR descriptor The ISR descriptor is a five byte area of memory with the following format: +-------------------------+ 1 byte | Device number (0 - 3) | +-------------------------+-------------------------+ 2 bytes | Offset of interrupt service routine | +---------------------------------------------------+ 2 bytes | Segment of interrupt service routine | +---------------------------------------------------+ EXIT CONDITIONS : none FUNCTION 24 - RESET DEVICE INTERRUPT VECTORS FUNCTION: This routine is used to reset the interrupt service routine back to the system defined service routine. ENTRY CONDITIONS: (FUNCTION) = 24 EXIT CONDITIONS : none FUNCTION 25 - NON-DESTRUCTED CHARACTER READ NO WAIT FUNCTION: If the device returns a character, then the next character that would be read is returned. This character is not removed from the input buffer. And this call allows the application to look ahead one input character. ENTRY CONDITION: (FUNCTION) = 25 EXIT CONDITION: (FUNC_RETC) = FF if character available = 0 if not (CHARACTER) = character if available