There are two sets of subroutine calls where each set is comprised of four call statements. One set of calls is used when the PCHSD2 is configured for the HSD mode and the other set of calls is used when the PCHSD2 is configured for the IBL mode. Both sets of calls are discussed in the following sections. Except for the OPEN routine, the HSD and IBL entry points are identical and may be used interchangeably.

NOTE: These routines use the "C" language calling conventions. If calling these routines from FORTRAN or other high level language, the appropriate high level language facility (e.g. the INTERFACE statement in FORTRAN) should be used.

Up to four PCHSD2's may be controlled by these subroutines, provided the user maintains a unique File Control Block (FCB) for each device. The user must not alter those portions of the FCB used by the I/O routines while the device is open.

The HSD subroutine calls must be used to insure proper operation of the PCHSD2 board. These four calls are described below.

The HSDOPEN routine must be called first to install the driver in the MS-DOS interrupt structure and initialize some necessary data structures. The user passes a File Control Block (FCB) address to the subroutine. This data structure is described in the example programs in APPENDIX A & B. The user must have filled in set-up information in the FCB. A typical calling sequence would be:

HSDOPEN(&fcb_blk,&cerr);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

cerr is an integer error return status code with the following meanings:

0 - successful open

1 - device not present.

2 - invalid Interrupt level.

3 - invalid DMA level.

4 - invalid DMA mode.

5 - invalid port address.

6 - too many devices (4 already open)

7 - this FCB already open

8 - board's status is bad; cannot be reset

(NOTE: The device inoperable and error code flags are set in the FCB status code if the PCHSD2 is determined to not be present or if the HSD device is not connected.)

The HSDSTRT routine is used to start an HSD transfer. The address of an FCB containing the address of an IOCB list is passed to this subroutine. In the NOWAIT mode, once the transfer is started, control is passed back to the calling routine. In the WAIT mode, the HSDSTRT routine waits for the IOCB list execution to finish. In the NOWAIT mode the calling routine determines when the transfer is complete by monitoring the device busy bit in the FCB status word 3 (1=busy; 0=not busy). A typical calling sequence would be.

HSDSTRT(&fcb_blk,&cerr);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

cerr is an integer error return status code with the following meanings:

0 - Successful start.

1 - Device not present.

2 - Device busy.

3 - Command error.

5 - Timeout

The HSDTERM routine is used to terminate any existing transfer in progress. A typical calling sequence would be:

HSDTERM(&fcb_blk,trm_cod);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

trm_cod is a binary value written to the PCHSD2 board's Control Register defining the type of Reset being issued. There are five types of Reset (which may be combined) and have the current binary value.

1 = PCHSD2 board HSD logic and FIFO Reset.

2 = External Device I/O Reset (Encore signal IOR).

4 = Terminate External Device transfer (Encore signal TDV)

The HSDCLOS routine is used to restore the MS-DOS interrupt structure back to its normal configuration. A typical calling sequence would be:

HSDCLOS(&fcb_blk,&cerr);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

cerr is an integer error return status code with the following meanings:

0 - successful close.

2 - device busy.

5 - timeout

The IBL subroutine calls must be used to insure proper operation of the PCHSD2 board when it is connected to a Encore Computer HSDII board which is operating in the IBL mode. These four calls are described below.

The IBLOPEN routine must be called first to install the driver in the MS-DOS interrupt structure and initialize some necessary data structures. The user passes a File Control Block (FCB) address to the subroutine. This data structure is described in the example programs in APPENDIX A & B. The user must have filled in set-up information in the FCB. The PCHSD2 will be configured to IBL mode with IBL (reversed) connectors and Low link arbitration priority, by default. The new port_sel field format in the FCB (see SECTION 3.3.3) may be used to override these options. A typical calling sequence would be:

IBLOPEN(&fcb_blk,&cerr);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

cerr is an integer error return status code with the following meanings:

0 - successful open

1 - device not present.

2 - invalid Interrupt level.

3 - invalid DMA level.

4 - invalid DMA mode.

5 - invalid port address.

6 - too many devices (4 already open)

7 - this FCB already open

(NOTE: The device inoperable and error code flags are set in the FCB status code if the PCHSD2 is determined to not be present or if the HSD device is not connected.)

The IBLSTRT routine is used to start an HSD transfer. The address of a FCB containing the address of an IOCB list is passed to this subroutine. In the NOWAIT mode, once the transfer is started, control is passed back to the calling routine. In the WAIT mode, the IBLSTRT routine waits for the IOCB list execution to finish. In the NOWAIT mode the calling routine determines when the transfer is complete by monitoring the device busy bit in the FCB status word 3 (1=busy; 0=not busy). A typical calling sequence would be.

IBLSTRT(&fcb_blk,&cerr);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

cerr is an integer error return status code with the following meanings:

0 - Successful start.

1 - Device not present.

2 - Device busy.

3 - Command error.

5 - Timeout.

The IBLTERM routine is used to terminate any existing transfer in progress. A typical calling sequence would be:

IBLTERM(&fcb_blk,trm_cod);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

trm_cod is a binary value written to the PCHSD2 board's Control Register defining the type of Reset being issued. There are five types of Reset (which may be combined) and have the current binary value.

1 = PCHSD2 board HSD logic and FIFO Reset.

2 = External Device I/O Reset (Encore signal IOR).

4 = Terminate External Device transfer (Encore signal TDV)

The IBLCLOS routine is used to restore the MS-DOS interrupt structure back to its normal configuration. A typical calling sequence would be:

IBLCLOS(&fcb_blk,&cerr);

fcb_blk is a File Control Block structure which contains status, set-up information and a pointer to the IOCB list.

cerr is an integer error return status code with the following meanings:

0 - successful close.

2 - device busy.

5 - timeout

The PCHSD2 card emulates the Encore HSDII card and thus all programming constraints are imposed by ensuring compatibility with the Encore HSDII card. This section provides information on the correct programming usage of the Encore File Control Block (FCB), the extended parameter area of the FCB, and the Input/Output Control Block (IOCB).

The principal data structures used are the File Control Block (FCB) and the Input/Output Control Block (IOCB). The structures used adhere as much as possible to the Encore FCB and IOCB definitions. In appendix A and B you will find example programs with "C" structure definitions compatible with the PCHSD2 subroutines.

Refer to the respective Encore MPXÄ32 Operating System Reference and Technical software manuals for a detailed description of the software requirements for the FCB and IOCB structure and the HSDII board operation. For a comprehensive hardware description of the Encore HSDII compatible card refer to

Encore HSDII Technical Manual, Document # 303-329131-000.

Encore MPX-32 Volume 2, Reference Manual, Document #323-001011-300

Refer to the following documents for programming assistance of the IBM compatible PCHSD2 card.

IBM PC/AT Technical Reference Manual 1502494

IBM DOS Technical Reference Manual 6138536

ADS PCHSD2 Technical Manual 0900071

Encore MPX-32 Reference Manual, Volume 1 323-001011-300

The File control block provides transfer parameters and working storage areas for the device driver routines. The FCB format is the same as that of the Encore FCB with the exception of an additional space. The PCHSD2 subroutines require an extended parameter area at the end of the FCB. It is 34 bytes long and contains set-up parameters and work area necessary for the PCHSD2 hardware configuration. It is described in detail in the following sections.

The File Control Block (FCB) must be set up by the user to describe each logical file within a task, and to describe certain attributes of each logical I/O operation.

In addition, certain information collected during each I/O operation is made available to the user via the corresponding FCB.

SECTION 3.3.1 contains detailed information on the Encore File Control Block as described in the MPX-32 Reference Manual, Volume I, Section 7.9. This information is repeated here to aid the user in better understanding how the Encore File Control Block is utilized by the MPX-32 Operating System.

This information shows how the Encore MPX-32 Operating System uses the FCB. It does not show how the PCHSD2 utilizes the FCB.

A logical file code is required. A Transfer Control Word (TCW) indicating transfer count and data buffer address for I/O operations controlled by this FCB is required. The Input/Output Control System (IOCS) assumes the following if no other special I/O characteristics are defined in the FCB:

Wait I/O - IOCS returns to the calling task only when a requested operation on the file or device assigned to this FCB is complete.

Automatic retry on error by an IOCS.

Device dependent output and input are handled using standard techniques.

Status information is returned in the FCB.

File and device access is sequential.

Also certain areas of the FCB can be used to define:

No-Wait I/O - Immediate return to the calling task after I/O operation is queued. User can define address to return to in task when processing is complete (normal or error).

Error Processing Inhibit - Only status is returned by handlers. No error processing by IOCS or handlers.

Special device output characteristics.

Expanded Transfer Control Word (TCW)

Some areas of the FCB are defined by I/O Control System (IOCS). IOCS stores the opcode each time the task specifies a particular FCB, stores status returned by handlers, tracks actual record length in bytes for each transfer, and builds and maintains I/O queue and File Assignment Table (FAT) addresses. All but Words 0 and 1 are optional. The user should initialize to zero all portions of the FCB that he wants to let IOCS or handlers set up or that IOCS must handle. The following table describes six of the sixteen FCB words with a description of their respective bits.

NOTE: The sixteen FCB words are defined as Words 0 thru 15. These words are further defined in SECTION 3.3.1.

FCB Bit Descriptions

Word/Bit Descriptor Description

1/12 F Format: 1=byte, 0=other

1/30 C Code: If Format = 1: byte number.

If Format = 0: 00=word, 01=left halfword, 11=right half word

Control Flags - Special Format Indicators Set by User

2/0 NWT* No-Wait I/O (Words 13-14). Else: Wait I/O

2/1 NER No error return processing.

2/2 DFI* Data Format Inhibit. Use format in Bits 8-12.

2/3 NST No status check by handler; no status returned. All I/O appears to complete without error.

2/4 RAN Random Access (user supplies address in Bits 13-31) Default: Sequential. IOCS supplies address.

2/5 BL Blocked I/O, disc/tape only. Else: based on assignment. Used Only by the M.File service.

2/6 EXP Go to Words 8, 9, 10 instead of Words 1 and 2. Default: Words 1 and 2.

Word/Bit Descriptor Description

2/7 IEC Task will not abort.

2/8 DFD Device Format Definition. When set, special definitions for 7Ä track magnetic tapes, ALIM's, ADS's, etc. are indicated in bits 9-12.

Status Flags Set by Handlers and System

3/0 OP Operation in Progress. (I/O request has been queued) Bit is reset after I/O post processing is complete.

3/1 ERR Error Condition found.

3/2 BB Invalid blocking buffer control pointers encountered in blocking or deblocking.

3/3 PRO Write protect violation.

3/4 INOP Device is inoperable.

3/5 BOM BOM (load point) or illegal volume number (multivolume) on magnetic tape.

3/6 EOF End of File (TSM also sets this bit when CTRLC typed on terminal)

3/7 EOM End of Medium (TSM also sets if other than CR at bottom of screen) (End of tape, end of disc file).

Status for Extended I/O Devices Returned by Handlers

3/10 TIME Last command exceeded timeout value and was terminated.

3/16 CDT Command Device Terminate.

3/19 RECR Record Length Error status.

3/20 PERR Parity Error status.

3/21 NPM Non-present Memory Error status.

3/22 IVLD Invalid opcode in IOCB Word 0 Error status.

3/23 DEV Device Inoperable Error status.

3/24 BUFF Data Buffer Overflow Error status.

3/25 EXT External Terminate.

3/26 IOCB IOCB Address Error.

3/27 ADDR Error on Transfer-In Address Fetch.

3/28 EOB Device End-of-Block.

3/29 EP5 Error Precluded Request Queuing.

3/30-31 ERR 00 - Data Transfer Error.

01 - Device Status.

10 - Command Transfer

Word/Bit Descriptor Description

Special I/O Status

6/0 No-Wait I/O Normal End Action address not executed.

6/1 No-Wait I/O Error End Action address not executed.

6/2 KILL command. I/O was not issued.

6/3 Exceptional condition occurred in I/O request.

Any of these functions may return a value of -1, with the variable errno set to one of the following error codes:

EFAULT If some part of a data structure passed as an argument is not accessible to the user.

EINVAL If some field in a data structure passed as an argument is invalid or inappropriate.

ENXIO If the requested operation is illogical or impossible.

EIO If some I/O error occurred on the VMEHSD.

EBUSY If active I/O requests preclude performing the current request.

EPERM If the caller does not have the requisite privilege for the requested operation.

EINTR If a signal was caught during the course of the current function call.

Each subsection below discusses one of the ioctl functions and describes the required argument(s). Detailed information about the various data structures may be found in section 3.0.

The following sections describe in detail the Encore FCB words 0 thru 15. Remember that all words are optional except words 0 and 1.

IOCS defines the I/O operation indicated by the task (READ, WRITE, etc.) in terms of the operation allowed on an assigned device or file; user defines the logical file code (lfc) used externally to assign a file or device for the operation.

Bits 0-3 This field is always zero.

Bits 4-7 Operation Code - IOCS uses a single hex digit to indicate the type of function for the device handler. Allowable functions and their definitions are unique to each peripheral device.

Bits 8-31 Logical File Code - Any combination of three (3) ASCII characters is acceptable. Must be supplied by user.

This word (or Words 8 and 9 if bit 6 of Word 2 is set) supplies a Transfer Control Word (TCW) used to access a data buffer or IOCL for I/O (see below). If no TCW definition is supplied, the transfer buffer defaults to location 0 of the task's logical address space (below the operating system) and is 4095 words (4KW) maximum.

Bits 0-11 Count - Three hex digits specify the number of units (bytes, halfwords, or words) to be transferred to or from a device or file. The count must include a carriage control character, if applicable. The units the count relates to are determined by the data buffer address in bits 12-31. The maximum value of this field is 4095 words.

The F bit (12) and C bits (30 and 31) of the data buffer address are set by IOCS according to the definitions in the following bits.

Bits 12, Format Code - These bits specify byte, 30 and 31 halfword, or word addressing for data transfers. They are interpreted as follows:

Type of F CC Transfer (Bit 12) (Bits 30-31)

Byte 1 xx

Halfword 0 y1

Word 0 00

where:

xx - Byte number (00,01,10 or 11)

y - 0 = Left Halfword; 1 = Right Halfword

00 - Word

If a halfword or word transfer is specified and a device accepts only bytes, IOCS adjusts the count accordingly (times 2 or 4). If a byte transfer is specified and a device accepts only halfwords or words, IOCS checks to see that the number of bytes in the buffer is an even multiple of the requested transfer and that the data buffer address is on an acceptable boundary. If these conditions exist, IOCS adjusts the count accordingly and initiates the transfer. If the conditions are not met, the request is treated as a specification error.

Note that IOCS operations described above enable the user to specify byte transfers beginning on a word boundary or word transfers on any device, whether the device operates on bytes, halfwords or words.

Doubleword addressing is not allowed; IOCS will abort the task.

Bits 13-29 Data Buffer Address - Specifies the starting address of a data buffer reserved by the user for reads and writes.

or

Data/Command Chain Address - Specifies the address of an IOCL to use when the Execute Channel service (SVC 1,X'25') is called. The IOCL in turn supplies an IOCD entry describing the transfer count, buffer address and other control information for each command or data transfer to the device.

Word 2 provides optional control specifications for I/O. For High Speed Data (HSD) Interface applications, Word 2 bit meanings are as follows:

Bits 0-7 Operational Specifications - These eight bits enable the user to specify that special operations such as no-wait I/O be performed by IOCS. The meaning of each bit is provided in SECTION 3.3.1.

Note: If bit 6 of Word 2 is set, the expanded random access address in Word 10 is used instead of bits 13-31 above.

Bit 8 Request Device Status After Transfer - This bit indicates an IOCB should be added to the IOCL to retrieve device specific status after the data transfer has completed.

Bit 9 Send Device Command Prior to Data Transfer - This bit indicates an IOCB should prefix the data transfer to transmit a device command word to the device. The value sent is the 32-bit expanded random access address.

Bit 10 Disable Timeout for this Request - This bit indicates the operation will take an indeterminable period of time and the handler should wait an indefinite period of time for the I/O to complete. This generally only has meaning on read operations.

Bit 11 Set UDDCMD from Least Significant Byte of Word 2 - This bit indicates that the UDDCMD byte in the data transfer IOCB should be set to the least significant byte of the random access field of the FCB. This provides the ability to pass additional control information to the device without modifying the device driver.

Bits 24-31 If bit 11 is set, these bits define the UDDCMD field of the generated IOCB, overriding the default value from a handler table.

Word 3 returns I/O status. IOCS uses 32 indicator bits to return the status, error, and abnormal conditions detected by handlers during the previous or current device operation. The task can examine these bits as needed. Individual bit assignments for bits 0-7 apply to any device. Bits 8-31 mean different things depending on the device. For non-extended I/O devices, test status, controller (DCC) status, and device status are returned as described in SECTION 3.3.1. for HSD Interface applications.

For High Speed Data (HSD) Interface applications, Word 3 error status bits have the following meanings:

Bits 17-18 unused

Bit 19 Record length error

Bit 20 Parity Error

Bit 21 Nonpresent memory (NPM)

Bit 22 Invalid opcode in IOCB Word 0

Bit 23 Device inoperable

Bit 24 Data buffer overflow

Word 4 defines record length. This word is used by IOCS to indicate the actual number of bytes transferred during a read or write.

Word 5 defines I/O queue address in bits 8-31. This field is set by IOCS to point to the I/O queue for an I/O request initiated from this FCB.

In bits 0-3, IOCS returns special status bits as described in SECTION 3.3.1. Bits 4-7 are not used.

Word 6 defines a wait I/O error return address in bits 8-31. Specify the address to transfer control to in the case of an unrecoverable error. If this field is not defined, an unrecoverable error is detected, and the user has not set bits 1 and 3 of Word 2 to inhibit error processing, IOCS aborts the task.

Word 7 must not be written by the user. It defines the File Assignment Table (FAT) entry associated with all I/O performed on behalf of this FCB. The FAT address is supplied by IOCS.

Word 8 begins expanded TCW definition. This area of the FCB can be used to define transfers larger than 4095 words, e.g., for extended I/O devices.

Bits 8-31 Expanded data buffer address - specifies the start address of a data buffer reserved by the user for reads or writes. This must be a logical byte address with no format bit present. Word bounding is required for some devices if unblocked.

or

Expanded Data/Command Chain List Address - Word address that points to the data or command chain list (IOCL) if using Execute Channel service, SVC 1, X'25'.

Bits 0-31 Expanded transfer count - eight digits specify the number of bytes to be transferred. Note that the transfer count supplied here is always in byte units. Must include the carriage control character, if applicable.

Word 10 defines expanded random address. This word contains a block number (zero origin relative to the beginning of the disc file). It is the start address for the current read or write operation.

For High Speed Data (HSD) Interface requests in non-Execute Channel Program format, this word defines a device command.

Word 11 returns status.

Bits 0-31 Status word 1 - for extended I/O, if an error is detected during an I/O operation, these 32-bits are returned by the SENSE command.

For High Speed Data (HSD) Interface applications, this word contains status sent from the user's device. Remember that each external device has its own unique status bit descriptions.

Word 13 defines normal return address for no-wait I/O. In bits 8-31, specifies address to transfer control to when a no-wait I/O operation is complete. The code at this address must be terminated with a call to IOCS for post-processing service (SVC 1,X'2C').

For High Speed Data (HSD) Interface applications, this address plus 1 word is the location to which control is transferred on asynchronous notification.

Word 14 defines an error return address for no-wait I/O. In bits 8-31, specifies (optionally) the address to transfer control to when no-wait I/O completes with an error. The code at this address must be terminated with a call to IOCS for post processing service (SVC 1,X'2C').

Word 15 defines a user-supplied blocking buffer address for device independent I/O or a Post Programmed Controlled Interrupt End Action Receiver for device dependent I/O.

The various addresses in the Encore FCB plus the extended parameter area used by the PCHSD2 are listed below. These addresses define information which the user must place information into, contains status information, or is used by the program. Refer to the following sections to determine what is required fill-in information and what is status. The first byte address is 0. Refer to the example program in APPENDIX A for additional clarification.

name offset byte description

(bytes)(lngth)

-------- ------ -------- ----------------------------------

nowait 8 4 Wait/nowait [MSB (Encore bit 00)]:

0 = wait,

1 = nowait

sts_flg 12 2 Transfer status flags

mod_flg 14 2 Mode flag: HSD/IBL mode

sts_msk 16 2 Status Mask

ioc_cnt 18 2 Count of executed transfer commands

cur_iocb 20 4 Currently executing IOCB address

iocl_ptr 32 4 Address of starting IOCB

tim_out 36 2 Time-out count in units of 0.1 seconds

tim_cnt 38 2 Local counter

pchsd_stat 44 4 PCHSD2 status word

hsd_stat 48 4 HSD returned status

end_act 52 4 Normal end action subroutine

err_end 56 4 Error end action subroutine

port_sel 64 2 A/B port select & byte/word swap

pc_ctl 66 2 PCHSD2 I/O port address

resrv5 68 6 Area reserved to I/O subroutines

dma_chn 74 2 Binary DMA channel

dma_mod 76 2 Binary DMA mode

irq_lev 78 2 Binary interrupt request level

old_vec 80 4 Saved DOS vector

spr_cnt 96 2 Count of spurious interrupts

Compatiblity note: all areas not defined by this table and areas labeled "reserved" have different uses in the PCHSD and PCHSD2 I/O routines. Any program which uses, or depends on the contents of these fields may require modification to use these I/O routines.

The extended parameter area is 34 bytes at the end of the Encore File Control Block. This is byte addresses 64 thru 97. Prior to an HSDOPEN or IBLOPEN call the caller must fill in the extended parameter FCB values for the following:

port_sel Port A/B Select & byte/word swap. This field has two formats. The old format is compatible with the PCHSD and its I/O software:

0040 = Byte swap

0080 = Word swap

00C0 = Byte & Word swap

The new format is selected by setting the FCB_NEW flag (bit 21) of the nowait field:

0001 = Byte swap

0002 = Word swap

0003 = Byte & Word swap

0080 = Enable High IBL link priority

0100 = Select HSD (normal) connectors

0600 = Select IBL (reversed) connectors

pc_ctl PC Control/Status port: (Hex 100 thru 1FFF)

dma_chn DMA Channel Number: ( 5 thru 7)

dma_mod DMA Access Mode:

0000 = demand

0x40 = single

irq_lev Interrupt Request Level: (3, 5, 9, 10, 11, 12, 15)

(see Appendix A for FCB "C" structure).

Prior to an HSDOPEN or IBLOPEN call the caller must fill in selected areas of the normal Encore FCB. This information is contained in byte addresses 00 thru 63. These areas are shown in the following:

nowait Wait/nowait [Encore bit 00 or PC bit 31 of a long word];

0 = wait,

1 = nowait

IOCB List Auto-Restart [Encore bit 08 or PC bit 23 of a long word]

0 = normal operation

1 = Auto-restart (see SECTION 3.5)

New port_sel field format [Encore bit 10 or PC bit 21 of a long word]

0 = Old format (compatible with PCHSD)

1 = New format

No Reset [Encore bit 09 or PC bit 22 of a long word]

0 = Issue I/O Reset to device on HSDOPEN

1 = Do not issue I/O Reset.

lcp_adr LCP pointer (starting IOCB list pointer)

tim_out Time out count in 1\10 seconds (decimal value)

end_act Normal end action subroutine address

err_end Error end action subroutine address

Various status information is available to the user. This information is presented in the following places:

ioc_cnt 18 2 Count of executed transfer commands

sav_iocb 20 4 Currently executing IOCB address

pchsd_stat 44 4 PCHSD2 status word

hsd_stat 48 4 HSD device returned status

The Status Flag area is FCB bytes 12 and 13. This is FCB word 3, Encore bits 00 thru 15. This is a 16-bit field but only four status bits are used, which are indicated below:

Encore Bit 00 - PC Bit D15 - Device Busy = 1; Not Busy = 0

Encore Bit 01 - PC Bit D14 - Error Condition Detected = 1

Encore Bit 02 - PC Bit D13 - External Device Interrupt = 1

Encore Bit 03 - PC Bit D12 - PCHSD2 is currently OPEN = 1

Encore Bit 04 - PC Bit D11 - Device Inoperable = 1

Encore Bit 08 - PC Bit D07 - IOCB Restart Sequence = 1

(refer to SECTION 3.5)

Prior to an HSDSTRT or IBLSTRT call the calling routine must first fill in the pointer to the IOCB list lcp_adr. (Notice that this pointer must be a far pointer.)

The IOCB list is an array of structures which the calling routine must fill in. The normal HSD bit definitions are adhered to strictly. The following HSD functions, which are described by IOCB Word 1, opcode bits 00 - 07, are supported:

Bit 00 - HSD I/O Transfer.

Bit 01 - HSD Command Transfer.

Bit 02 - HSD Status Request.

Bit 04 - HSD Interrupt on End-of-Block (IEOB).

Bit 05 - HSD Xfer-In-Channel (TIC). Subtract one and branch non-zero.

Bit 06 - HSD Command Chain.

Bit 07 - HSD Data Chain.

(Note that addresses in the TIC and IEOB are always far addresses. The routine for the IEOB call must be an assembly routine which returns via an RETF instruction.)

There are some features of this program that are not described in the Encore documentation. Information is presented in the following sections to help better described these non-standard enhancements.

There are special features when the PCHSD2 board is being used in the IBL mode. These features are described in the following paragraphs.

In the FCB nowait field Bit 8 of Word 2 [or the most significant bit of byte 9 (i.e., Encore bit 08 or PC long word bit 23)] is used to indicate that an IOCB list should restart a sequence following completion of the current IOCB list.

In the first word of any IOCB device dependent bits 13, 14, and 15 have special meaning. This is Encore bits 13, 14 and 15 or PC bits 18, 17 and 16.

Bit 13 - call an user's subroutine whose address is contained in the second word of the IOCB. This subroutine is a far pointer call and should return with an "RET" instruction. The subroutine must establish the Data Segment (DS) register for data accesses.

Bit 14 - if bit 15 is set then a Link Request will be issued, otherwise the device will wait for a Link Request from the external device.

Bit 15 - a flag to indicate that a link must be established prior to execution of the IOCB.

There are certain requirements that must be met if using the external device to interrupt the PCHSD2.

1 - The External Device Interrupt is enabled by the HSDOPEN routine. Refer to SECTION 2.2.1.

2 - The PCHSD2 Interrupts are also enabled by the HSDOPEN routine at this time.

3 - The External Device Interrupt is disabled when the HSDCLOS routine is called. Refer to SECTION 2.2.4.

Servicing of this external interrupt is handled differently if the computer is executing an IOCB, or if it is in some other area of the applications program and not executing an IOCB.

If the applications program is not currently executing an IOCB, then when an External Device Interrupt is received, the File Control Block (FCB) Word 03, Bit 02 status bit will be set. This bit is described in SECTION 3.3.5.1. A check is then made to determine if a Normal End Action Routine Address is present in the File Control Block Word 13 (offset bytes 52 - 55). If no End Action Address is present then the External Device Interrupt is ignored. If an End Action Address is present, then the End Action routine is executed. The External Device Interrupt Status bit in the File Control Block Word 3, bit 02 is reset when the program returns from the End Action routine.

If the applications program is currently executing an IOCB, then when an External Device Interrupt is received, the File Control Block (FCB) Word 03, Bit 02 status bit will be set. This bit is described in SECTION 3.3.5.1. Two checks are then made. The first one determines if a Normal End Action Routine Address is present in the File Control Block Word 13 (offset bytes 52 - 55). The second one determines if the Interrupt-on-End-of-Block bit is set in the current IOCB (this bit is defined in IOCB word 1, opcode field bit 04). If both checks are true, then upon completion of this current IOCB the End Action routine is executed. The External Device Interrupt Status bit in the File Control Block Word 3, bit 02 is reset when the program returns from the End Action routine. If the above two checks were not true the External Device Interrupt remains set until the two checks become true or it is reset by the applications program.

Normal End Action occurs when the PCHSD2 determines that the signals Operation Complete and Interrupt-on-End-of-Block (IEOB) are set. Also there must be an Normal End Action address set in File Control Block Word 13.

Error End Action occurs when the PCHSD2 determines that one of two conditions has occurred.

1 - The signal External Terminate (EXT) is set or

2 - Device-End-of-Block (DEOB) with Transfer Count not zero is set.

Also there must be an Error End Action address set in File Control Block Word 14.

To use the end action routines certain requirements must be met. The requirements are presented below.

1 - The routine may be an assembly language or C routine. If written in C, it must be compiled with stack checking disabled.

2 - It must be a Far Procedure with a RETF.

3 - The routine must save all registers that it changes.

4 - It will be passed the Far address of the File Control Block on the stack. (The I/O routine will remove this argument from the stack on return, according to the C language calling convention.)

5 - To access data in the main program, the user must point the data segment register to _DATA segment if compiled under Medium Model or FAR_BSS if compiled under Large Model.

6 - To set the File Control Block (FCB) end action address perform:

Declare as "void far ENDACT ();"

fcb.end_act = ENDACT;

NOTE: Refer to the File Control Block Structure. Also the name ENDACT is not required.