Software:

• IRIX 6.5 Operating System, version 2.2.x, including "C" compiler.

Hardware:

• Silicon Graphics Challenge or Onyx System with VMEbus adapter and DMA mapping hardware.
• VMEHSD Card.

Knowledge of the Encore HSDII IOCB structure will aid in using the VMEHSD board and software.

The VMEHSD driver is installed as a standard IRIX(TM) device driver. It can handle up to eight (8) VMEHSD's configured for either HSD or IBL mode. The following system calls are supported:

• OPEN
• CLOSE
• READ
• WRITE
• IOCTL

Arguments to the IOCTL call provide for reading and/or setting the device configuration and operating mode, for issuing commands to and reading status from an HSD-connected device, and for starting and controlling I/O operations using an IOCB list.

Within the following descriptions, the term configuration is taken to include the relatively static aspects of the VMEHSD configuration: such things as interrupt level, HSD/IBL mode, etc., which would normally be associated with board configuration jumpers, but which are programmable on the VMEHSD. The term (operating) mode refers to more dynamic parameters, mostly concerned with driver software functions.

All VMEHSD's have the same major device number which may be set to any convenient value for a particular system. All VMEHSD's in a system are accessed via character special devices with the eight-bit minor device number identifying one of the eight possible VMEHSD's and possibly dictating its operating configuration. Access to a device with a particular minor device number does not change its configuration, but merely insures that the configuration is set as the user requires. For example, attempting to open a device whose minor device number requires IBL configuration while the device is set to HSD configuration will cause the open to fail with the return "no such device". The "configuration" device is used only to change the configuration of the VMEHSD and may not be addressed for any I/O operation.

The minor device number is encoded as follows:

x u u u c c c c

---Device number--     ------Configuration-----

CONFIGURATION:

Configuration options include:

          0 0 0 0     ANY configuration (HSD or IBL)
          0 0 0 1     HSD configuration only
          0 0 1 0     IBL only (normal or swapped)
          0 0 1 1     CONFIGURATION device
          0 1 x x     IBL mode with specific connector configuration and priority jumper setting.
          0 1 1 x     IBL, normal (HSD) connector configuration.
          0 1 0 x     IBL, swapped (IBL) connector configuration.
          0 1 x 0     IBL, Low Priority
          0 1 x 1     IBL, High Priority

DEVICE NUMBER:

Configuration data is set to a default condition at system boot-up and may be changed only when accessing the "configuration" device (minor device where 'U316' is the VMEHSD unit number [0-7]). Read and Write access to any VMEHSD device are equivalent, and are governed by the file access permissions on the associated device file.

The VMEHSD driver provides two methods of initiating a link for data transfers in the InterBus Link (IBL) configuration. The default mode does not initiate any link request, but expects to wait for, and acknowledge a link request before each data transfer. A flag in the hsdmode structure passed to an HSDSETMOD call may be set to indicate that the VMEHSD should initiate the link request for all transfers.

The alternate method emulates the Encore H.IBLG handler and initiates the link request when the first operation is a Write or waits for and acknowledges a link request when the operation is a Read. This method is selected by a flag in the hsdmode structure passed to an HSDSETMOD call.

The header file hsdio.h contains definitions of symbols used with the ioctl(2) system call to perform various HSD functions, as well as declarations for data structures used with those calls.

The standard open(2) function must be called to associate a file descriptor with the desired device file. No specific meaning is attached to the "flag" or "mode" arguments. Only one process may open any one VMEHSD device at a time. In addition to errors which may normally be returned from the open call, a value of EBUSY (in errno) may be returned if the addressed device is already in use.

The standard close(2) function must be called to terminate access to the desired device file. Any pending operations for the open device are canceled and the associated memory areas released when the device is closed.

The standard read(2) function is used to transfer data from the VMEHSD to the user's buffer. All data transfers are performed directly to the user's buffer. Therefore, the user's buffer address must be aligned on a 32-bit boundary and the transfer byte count must be a multiple of four. The maximum length of a single transfer is 262,140 bytes (65535 or hex FFFF 32-bit words). This is the maximum that can be transferred by a single IOCB. If the requested transfer size exceeds the maximum, the driver will return an error (EINVAL). The xstatus value, which may be retrieved via an HSDPRVSTS call, will be EXLONG (transfer count too long).

Options on the read call are specified by flag bits set in the flags field of the hsdmode structure passed to an ioctl (HSDSETMOD) call:

HM_CBR Issue Device Command before reading. A Device Command IOCB is command chained before the list performing the requested data transfer. The device-dependent portion of the command is taken from the cmd-rd field of the hsdmode structure last used in an ioctl (HSDSETMOD) call. See Section 3.5 for information on how to specify the desired device command.

HM_SAR Request Device Status after reading. A Device Status Request IOCB is command chained to the end of the list performing the requested data transfer. The ioctl (HSDPRVSTS) call may be used to retrieve the status returned by the device.

The HM_CBR and HM_SAR options are valid only for a VMEHSD operating in an HSD configuration. The HSDAUXCMD call may be used to specify an arbitrary IOCB list to be chained preceding the data transfer IOCL (see Section 2.9.14). The HSDAUXCMD option takes precedence over the HM_CBW flag if both are given.

The returned value will be the number of bytes actually received from the external device or will be -1 in case of an error. In addition to the errors which may normally be returned from the "read" call, the following additional conditions may be reported by errno values:

EINVAL Requested transfer length is not positive, is greater than the maximum allowed or is not a multiple of four bytes (1 longword).

EIO An error occurred in the data transfer.

ENOMEM A DMA mapping failure occurred, preventing the transfer from taking place. This error should not happen.

Further explanation may be obtained by issuing the ioctl (HSDPRVSTS) call and examining the returned xstatus field. (See Section 2.9.13.)

The standard write(2) function is used to transfer data from the user's buffer to the VMEHSD. All data transfers are performed directly from the user's buffer and the write call will not return until the data transfer to the external device is complete. The user's buffer address must be aligned on a 32-bit boundary and the transfer byte count must be a multiple of four. The maximum length of a single transfer is 262,140 bytes (65535 or hex FFFF 32-bit words). This is the maximum that can be transferred by a single IOCB. If the requested transfer size exceeds the maximum, the driver will return an error (EINVAL). The xstatus value, which may be retrieved via an HSDPRVSTS call, will be EXLONG (transfer count too long).

Options on the write call are specified by flag bits set in the flags field of the hsdmode structure passed to an ioctl (HSDSETMOD) call:

HM_CBW Issue Device Command before writing. A Device Command IOCB is command chained before the list performing the requested data transfer. The device-dependent portion of the command is taken from the cmd-wt field of the hsdmode structure last used in an ioctl (HSDSETMOD) call. See Section 3.5 for information on how to specify the desired device command.

HM_SAW Request Device Status after writing. A Device Status Request IOCB is command chained to the end of the list performing the requested data transfer. The ioctl (HSDPRVSTS) call may be used to retrieve the status returned by the device.

The HM_CBW and HM_SAW options are valid only for a VMEHSD operating in an HSD configuration. The HSDAUXCMD call may be used to specify an arbitrary IOCB list to be chained preceding the data transfer IOCL (see Section 2.9.14). The HSDAUXCMD option takes precedence over the HM_CBW flag if both are given.

The returned value will be the number of bytes actually transferred to the external device, or -1 in case an error occurred. In addition to the errors which may normally be returned from the "write" call, the following additional conditions may be reported by errno values:

EINVAL Requested transfer length is not positive, is greater than the maximum allowable or is not a multiple of four bytes (1 longword).

EIO An error occurred in the data transfer.

ENOMEM A DMA mapping failure occurred, preventing the transfer from taking place. This error should not happen.

Further explanation may be obtained by issuing the ioctl (HSDPRVSTS) call and examining the returned xstatus field. (See Section 2.9.13.)

The ioctl(2) call is used to perform all VMEHSD operations other than simple data transfers. The ioctl call requires the user to pass the file descriptor of an open device file, a function code and an argument. All ioctl calls are performed synchronously. That is, the operation is completed and any status information to be returned to the caller is stored before control returns from the ioctl call.

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.

Argument: pointer to hsdconfig structure

This call returns the current configuration information to the referenced hsdconfig structure. This call may be performed on any device, provided no I/O activity is in progress.

Argument: pointer to hsdconfig structure

This call sets the configuration of the addressed VMEHSD according to the contents of the referenced hsdconfig structure. This call may be performed only on the configuration device (see Section 2.2), and only when no I/O activity is in progress. Note that the busadrs field of the hsdconfig corresponds to the VMEHSD jumper setting and may not be changed. Nor may the ivector field be changed by HSDSETCFG. Other fields may be changed, but extreme care should be used. To change configurations, use HSDGETCFG to obtain the current settings, then issue HSDSETCFG after altering the desired items.

Argument: pointer to hsdmode structure

This call returns the current operating mode information to the referenced hsdmode structure. This call may be performed on any device, provided no I/O activity is in progress.

Argument: pointer to hsdmode structure

This call sets the current operating mode of the addressed VMEHSD from information in the referenced hsdmode structure. This call may be performed on any device, provided no I/O activity is in progress. To change modes, use HSDGETMOD to obtain the current settings, then issue HSDSETMOD after altering the desired items. Issuing an HSDSETMOD call to the configuration device will cause the mode settings to become the defaults for all users until the system is next re-booted.

Argument: pointer to character string at least HSDMAXID

This call gets the identification string (including firmware revision level) from the addressed device and returns it to the caller's character string. The identification is an ASCII string terminated by a null byte and is not more than HSDMAXID (defined in hsdio.h) bytes long, including the null terminator.

Argument: reset mode selection

This call performs the requested reset operation(s) on the addressed VMEHSD. The argument to this function is a reset mode selection which may be defined in one of three ways:

a) Constants selecting individual reset operations:

• HSD_TERM: Issue "terminate device" function
• HSD_MCLR: Issue master clear (I/O Reset) function
• HSD_RESET: Issue board reset to VMEHSD

Two or more selections may be or-ed together; they will be performed in the order listed above.

b) The constant HSD_RSTCOD may be or-ed with the desired VMEHSD hardware reset code. The requested code will be issued to the board directly.

c) The constant HSD_HALT for the reset mode will result in termination of any currently active I/O operation. The driver in effect, simulates an immediate time-out and terminates the operation appropriately.

This function can be issued to any device. Unless the argument is HSD_HALT, there must be no currently active I/O operation on the device.

Argument: pointer to 32-bit word to receive status

This call issues a board status request to the addressed VMEHSD and stores the status in a 32-bit word addressed by the argument.

Argument: pointer to hsdctl structure

This call issues a device status request IOCB to the addressed VMEHSD and stores the VMEHSD and device status in the addressed hsdctl structure. The iocb_dsr field of the hsdctl is used as the source of the device-dependent portion of the device status request IOCB. This function can be issued to any VMEHSD which is operating as an HSD and which has no active I/O requests.

Argument: pointer to hsdctl structure

This call issues a device command, optionally followed by a Device Status Request IOCB to the addressed VMEHSD and stores the VMEHSD and device status in the addressed hsdctl structure. The iocb_cmd1 and iocb_cmd2 fields of the addressed hsdctl provide the device-dependent portion of the device command IOCB. If the SACMD flag is set in the hsdctl, a Device Status Request IOCB will be command chained to the device command IOCB. The iocb_dsr field of the hsdctl provides the device-dependent portion of the Device Status Request IOCB. This function can be issued to any VMEHSD operating as an HSD and which has no active I/O requests.

Argument: pointer to hsdctl structure

This call returns status from the last operation performed on the addressed device to the referenced hsdctl structure. The most recent board and external device status are stored in fields hsd_sts and dev_sts, respectively. The extended status code from the last operation is stored in the xstatus field and the value returned to the system errno variable from the last ioctl call is stored in the perrno field. This call is useful in obtaining more detailed information about a failed data transfer operation. It may be issued to any device at any time. The return value from this function is always zero, unless problems are encountered in accessing the user's hsdctl structure, in which case -1 will be returned and errno will be set to EFAULT.

Argument: pointer to hsdctl structure

This call allows the user to specify auxiliary device commands, status requests, and data outputs to be prefixed to the next read or write call. It also allows the user to specify a User Device-Dependent command for the Read or Write IOCB. The iocl field of the referenced hsdctl should point to the desired IOCB list (IOCL). The IOCL may contain Device Command, Device Status Request or Write Data IOCB's, only. The IOCL and any data to be written to the device, are moved to a buffer internal to the driver. At the next read or write call, the list copied from the HSDAUXCMD call will be prefixed to the IOCL required for the data transfer. When the I/O operation is complete, status stored by the VMEHSD in the driver's copy of the auxiliary IOCL will be posted back to the user's IOCL before return from the read or write is made. An HSDAUXCMD call with the iocl address set to 0 will cancel any pending HSDAUXCMD. This call may be issued to any device with no currently active I/O operation.

On any HSDAUXCMD call (regardless of whether the iocl address is 0) the contents of the uddcmd field of the referenced hsdctl will be saved. The saved value will be inserted into the User Device-Dependent Command (UDDCMD) field of the IOCB's used for the next READ or WRITE call. The UDDCMD field occupies bits 08-15 of the first word of a data transfer IOCB.

In addition to the errors returned by other ioctl functions, HSDAUXCMD may return an errno value of EINVAL with the hsdctl xstatus field set to one of the following:

EXAUX an invalid IOCB (not Device Command, Status Request or Write) is in the list.

EXLONG The IOCB list and all write data would not fit in the auxiliary kernel buffer defined for the device.

Note: The Device Command and Status Request IOCB's are legal in an HSDAUXCMD list, but are invalid for a VMEHSD operating in IBL configuration; it is the user's responsibility to insure this restriction is met.

The size of the driver's auxiliary buffer is determined at the time the kernel is built. See Section 5.2.2 for details of configuring the auxiliary buffer.

This section describes the data structures used with the ioctl(2) function calls to perform I/O operations with the VMEHSD. These data structures and the associated constants are defined in the file hsdio.h. Definitions for the standard HSD IOCB structure are found in the file hsddef.h.

Refer to the respective Encore MPX?32 Operating System Reference and Technical software manuals for a detailed description of the software requirements for the 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 assistance in programming the VMEHSD card:

The Device Command Block (DCB) is a block of eight (8) 32-bit words which provides the VMEHSD card with configuration information, a description of the operation to be performed and a place to return status information to the user. The first two 32-bit words of the DCB contain basic configuration information required for the VMEHSD to access the VMEbus and the address of the DCB. The VMEHSD is activated by writing these two 32-bit words to its command and pointer registers. Writing to the pointer register causes the VMEHSD to execute the operation specified by the contents of the command register. Therefore, the first 32-bit word of the DCB must be written to the command register before the second word is written to the pointer register.

Jumpers JP1-16 on the VMEHSD board determine the physical address of the VMEHSD command and pointer registers. The jumpers determine the upper 16-bits (bits 31-16) of the addresses. The lower 16-bits of the addresses are fixed at FEFC (hex) for the command register and FF00 (hex) for the pointer register. Jumper JP1 corresponds to bit 31 (most significant) of the physical address; JP16 corresponds to bit 16. Jumpers are installed corresponding to ones in the desired address. The factory setting is 0100 (hex), giving 0100FEFC (hex) for command register and 0100FF00 (hex) for pointer register.

The required DCB structure is managed by the VMEHSD driver so the user never needs to be concerned with its contents. Certain fields of the DCB are returned to the caller and may be modified by the HSDGETCFG and HSDSETCFG calls. For the user concerned with this level of detail, the DCB is described in detail in the ADS VMEHSD Technical Manual, document number 0900052.

The hsdconfig structure is used with the HSDGETCFG and HSDSETCFG calls to retrieve or change the VMEHSD's configuration. This structure contains the following information:

busadrs VMEbus address assigned to addressed VMEHSD

cfg_reg Current contents of VMEHSD configuration register. Significant bit sub-fields of this field are accessed by symbols defining appropriate masks:

• HSD_MODE HSD/IBL selection has value
• HSD_MHSD if operating as HSD
• HSD_MIBL if operating as IBL

• HSD_CCFG IBL connector configuration has value
• HSD_CHSD if configured with HSD (normal) connector
• HSD_CIBL if configured with IBL (swapped) connector
• HSD_HPRI IBL link high priority selection (set if high)
• HSD_SWP Byte/word swap selection
• HSD_EXISTS Bit is set in configuration if a VMEHSD at the configured address actually exists. Clearing this bit and issuing an HSDSETCFG call effectively takes the addressed device off-line.

irqlvl Configured VMEbus interrupt request level

ivector Configured VMEbus interrupt vector

brlmode VMEbus release mode selection

brqlvl VMEbus request level

am_dcb VMEbus address modifier for accessing DCB

am_iocl VMEbus address modifier for accessing IOCB lists

am_bfr VMEbus address modifier for accessing data buffers

The VMEbus address modifier (AM) lines allow a bus master to pass additional information about the slave during a data transfer. This information may be used to partition the system to increase reliability or to enhance memory/device protection and privileged access functions. Because system requirements vary, the VMEHSD allows the user to specify the address modifier bits to be used in accessing: 1) the DCB for control and status information, 2) the IOCB list and 3) the user's data buffer. The 64 possible AM codes are grouped into three categories: 1) defined by VMEbus specification, 2) defined by user, 3) reserved.

The recommended AM codes for basic I/O operations are:

Hex Value    Interpretation

09    Extended non-privileged Data Access

0D    Extended supervisory Data Access

0B    Extended non-privileged Ascending Access

The hsdmode structure is used with the HSDGETMOD and HSDSETMOD calls to retrieve or change the VMEHSD's operating mode. This structure contains the following information:

flags    Flag bits specifying options:

• HM_SWW Swap 16-bit words in data transfers
• HM_SWB Swap bytes in data transfer
• HM_CBR Issue device command before read
• HM_CBW Issue device command before write
• HM_SAR Request device status after read
• HM_SAW Request device status after write
• HM_LIN Initiate IBL link request on each data transfer
• HM_EEM "Encore Emulation Mode": Issue or acknowledge

  IBL link requests according to Encore H.IBLG handler protocol.

IBL link operations are summarized in the following table:

Operation HM_LIN HM_EEM Link

Any 0 0 Ack

Any 1 x Issue

Write 0 1 Issue

Read 0 1 Ack

timeout Default timeout to be applied to any operation not using an hsdctl structure or not having a timeout specified in the associated hsdctl structure.

cmd_rd Two-longword array containing the device-dependent portion of the device command used if HM_CBR is set. The lower 24-bits of the first word and the whole second word are placed in a device command IOCB which is command chained to the required data transfer IOCBs.

cmd_wt Two-longword array containing the device-dependent portion of the device command used if HM_CBW is set. The lower 24-bits of the first word and the whole second word are placed in a device command IOCB which is command chained to the required data transfer IOCBs.

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 is most significant and all bits are Hi True):

Bit 00 - HSD I/O Transfer (1 = Input & 0 = Output).
Bit 01 - HSD Command Transfer.
Bit 02 - HSD Status Request.
Bit 04 - HSD Interrupt on End-of-Block (IEOB).
Bit 05 - HSD Transfer-In-Channel (TIC).
Bit 06 - HSD Command Chain.
Bit 07 - HSD Data Chain.

The VMEHSD also supports in firmware the SOBNZ (subtract one and branch non-zero) variant of the TIC IOCB as defined by the Encore generic HSD handler, H.HSDG. For this function, the third word of a TIC IOCB must contain two 16-bit counters. The least-significant one (bits 16-31) is decremented each time the TIC is processed and a branch to the target address is taken. When the count in bits 16-31 reaches zero, it is reset to the value in bits 0-15 and the branch is not taken, causing the IOCB at the next sequential address to be fetched and executed.

The hsdctl structure is used with all ioctl calls which initiate an I/O operation or retrieve external device status. This structure contains the following information:

flags Flag bits specifying options:

• SACMD Issue device status request after performing command on an HSDDEVSTS call.

timeout Time limit in seconds to allow for completion of this operation. If zero, the most recent value set by an HSDSETMOD call will be used. If no value previously set by HSDSETMOD, default is 30 seconds.

xstatus Extended status information. The value returned in this field on an HSDPRVSTS call gives additional information about the reason for termination. See Section 4.0 for a detailed list of status codes.

perrno Previous value of system variable errno, returned on HSDPRVSTS call only.

iocb_dsr Low-order 24-bits of this word are placed in the first word of the device status request IOCB issued by an HSDDEVSTS or HSDDEVCMD (if SACMD flag set) call.

iocb_cmd1 Low-order 24-bits of this word are placed in the first word of the IOCB issued by an HSDDEVCMD call.

iocb_cmd2 This word is placed in the second word of the IOCB issued by an HSDDEVCMD call.

hsd_sts Most recent status stored by the VMEHSD is returned to this field at completion of any operation.

dev_sts Status returned by the external device is stored here by an HSDDEVSTS or HSDDEVCMD (with SACMD set) call.

iocl Pointer to IOCB list to be executed.

Note: The header file hsdio.h defines additional fields in the hsdctl structure for compatibility with previous versions of the driver. Only those elements listed here are valid for use with the IRIX 6.5 driver.

Status returns from the system calls used to access the VMEHSD driver are consistent with other UNIX device drivers. In addition, status information may be returned to the hsdctl structure associated with the call, and may be stored in the IOCB list used.

In case of an error, the system function called will return -1 and the variable errno will be set to an error code. Some status returns are specific to the VMEHSD driver and may differ from the meaning associated with the same return from another device.

The xstatus field of the hsdctl structure contains an expanded error code in the case of an EINVAL, EFAULT, or EIO return. The expanded values are as defined in hsdio.h.

Expansion of EFAULT code:

EXIOLA Unable to access some part of IOCB list.

EXBUFA Caller unable or unauthorized to access some part of a data buffer addressed by the IOCB list.

Expansion of EINVAL code:

EXBUFB IOCB specifies buffer address not on a 32-bit boundary.

EXCNT IOCB specifies I/O transfer count of 0.

EXCHN Chaining error on IOCB (DC and CC).

EXCMD Command or Status request IOCB is in error.

EXLONG If operation is read or write: data transfer request is too long. If operation is ioctl (HSDAUXCMD): list and data will not fit in device's auxiliary kernel buffer.

EXAUX Invalid IOCB type (not Device Command, Status Request, or Write Data transfer) found in the list passed to a HSDAUXCMD call.

Expansion of EIO code

EXTIMO Request not completed before timeout occurred.

EXKILL Request aborted by HSDHALTIO or HSDRESET, HSD_RESET call.

EXIOER Actual VMEHSD I/O error (see hsd_stat field for bad status value).

The hsd-sts field of the hsdctl structure contains the status returned by the addressed VMEHSD on the last operation. This status is also stored in the fourth word of any IOCB other than a TIC or Device Status Request.

Format of the VMEHSD status word is:

• Bit 31 Current IOCB specifies a read operation
• Bit 30 Current IOCB specifies command transfer
• Bit 29 Current IOCB specifies status request
• Bit 28 Current IOCB specifies data chaining
• Bit 27 Current IOCB specifies command chaining
• Bit 26 Link request was received (IBL mode only)
• Bit 25 External terminate received from device
• Bit 24 Device End-of-Block signal received
• Bit 23 Operation complete
• Bit 22 External device present
• Bit 21 Output FIFO empty
• Bit 20 Output FIFO half full
• Bit 19 Input FIFO empty
• Bit 18 Input FIFO half full
• Bit 17 Not external mode
• Bit 16 Transfer counter non-zero

• Bits 15-0 Residual count. Number of 32-bit words requested but not transferred.

The VMEHSD device driver is distributed on 4mm DAT tape in tar format and contains the following components:

Device driver code:

• Part Number 0950111

SETHSD Utility:

• Part Number 0950045

Copy the installation files from the distribution tape:

tar xvf /dev/tape

The following files should be placed in a convenient directory for compiling the driver:

• hsd_dt.h VMEHSD device table structure declarations
• vhsd.c VMEHSD driver source
• vhsd.master Description of VMEHSD driver for IRIX
• vhsd.sm File describing VMEHSD hardware
• Makefile.vhsd Instructions for building driver, sethsd
• bld.kern Shell script to compile driver and build new IRIX kernel
• mkhsdfiles Shell script for creating HSD device nodes in /dev directory

The following files should be placed where they are accessible to programs compiled to use the VMEHSD driver.

• hsddef.h Structure declarations for IOCB contents
• hsdio.h Structure and symbol definitions for users of the VMEHSD driver

Edit the file vhsd.sm to describe the target configuration. Each VMEHSD is described by a VECTOR directive such as the following. The entire directive is a single line although it is broken up here for illustration.

VECTOR bustype=VME module=vhsd ipl=4 ctlr=0 adapter=0 iospace=(A32S,0x20000000,0x10000) exprobe_space(r,A32S,0x2000FF04,4,0x564D4548,0xFFFFFFFF)

The following items may be changed in each VECTOR line:

ipl VMEbus Interrupt Priority Level for the board (may be a value from 1 through 7). Interrupt vectors will be allocated by the driver when the system is booted.

ctlr VMEHSD "unit" number. These should be assigned sequentially, starting from 0, and may not exceed 7.

adapter The number of the VMEbus adapter to which this VMEHSD is attached. Should be zero except for systems with more than one VMEbus adapter.

iospace The second argument specifies the VMEbus address of the device and must match the VMEHSD address jumper setting (JP1) exactly. The other arguments must not be changed.

exprobe The third argument specifies the VMEHSD register to probe to see if the board is installed. This value must be equal to the bus address specified by iospace plus (hex) FF04. The other exprobe arguments must not be changed.

Note that when a probe address is given, lboot will include the VMEHSD driver and tables only for devices that are physically present. To include the driver in the kernel unconditionally, delete the part of the VECTOR directive(s), from exprobe to the end of the line. Refer to the comments in the file /var/sysgen/system/irix.sm to select appropriate VMEbus addresses which are reserved for customer devices.

A typical configuration for a VMEHSD on an IP19 processor is:

VMEbus address (jumper):  2000000016
Base (iospace) address:  2000000016
Interrupt Priority Level:  4
Bus Request Level:  3

The vhsd.master file may be edited to set the major device number used for VMEHSD devices and the sizes of buffers allocated for HSDAUXCMD operations. The major device number is given in the "SOFT" field of the first non-comment line of the file. It should be chosen from the range of values reserved for customer devices so as not to conflict with other devices in the system. If this number is changed, the same value must be given to the mkhsdfiles script to create the VMEHSD device files.

The symbols SIZE_0 through SIZE_7, defined in this file, specify the length, in (32-bit) longwords, of the auxiliary buffers used for VMEHSD units 0 through 7, respectively. The default value is 1024 longwords (4096 bytes). An auxiliary buffer must be large enough to accommodate the user's auxiliary list (4 longwords per IOCB) as well as all data to be written with the list. However, this buffer is allocated by the driver at boot time and reduces total available memory, so its size should be kept as small as practical. Auxiliary buffers are not defined for devices which are not configured. DMA mapping hardware for the auxiliary buffer, as well as for the largest permissible user buffer are allocated when the device is opened and freed when it is closed.

To alter the size of an auxiliary buffer, set the corresponding SIZE_n symbol to the desired length, in longwords. To suppress use of the auxiliary buffer, set the length to 0. Note that if no auxiliary buffer is defined for a particular VMEHSD, an HSDAUXCMD call addressed to that unit will always return EINVAL, with xstatus set to EXLONG (IOCB list too long for auxiliary buffer).

Compile the driver by invoking the bld.kern script or by performing the following steps manually:

1. Determine the processor model (IP5, IP12, IP19, etc.) being used. The hinv command may be used to determine this value.
2. Set the environment variable CPUBOARD to the appropriate processor model number. For example:
   setenv CPUBOARD IP19
3. smake -f Makefile.vhsd vhsd.o

To view example programs, please download the printable version.