NOTES ON THE USE OF THE 10103 DRIVER 18 June, 1992 IKON Corporation Seattle, WA, USA This document contains a brief set of notes on the calling sequences used with the driver for the 10103 Sbus DR11 emulator from IKON Corporation. It will describe the general purpose of each ioctl() call, and attempt to give suggestions as to how they might be used. It will also describe the compile-time configuration defaults and choices available. Since the DR11 is a very general-purpose board, it is impossible to give examples of all possible uses of the board and driver. The user is referred to the hardware manual provided with the 10103. It contains register descriptions, and some discussion of how DVMA transfers and interrupts are used. The driver's header file, idrio.h, contains register descriptions, and the #define statements for the arguments to be used in ioctl() calls to the 10103 driver. It must be included in the code of the program calling the driver. (#include "idrio.h") The c program, idrlink.c, which is included on the driver diskette, is a very simple example of how the 10103 and driver might be used. A call to the 10103 driver looks like: ioctl(filedes,cmd,arg) ; Filedes is a filedescriptor returned by the open() call. Cmd is one of the pre-defined commands from idrio.h. Arg (when used) is a pointer to one, or a combination, of the arguments defined in idrio.h. Arg is typically defined as an array of unsigned integers. An code fragment that opens the 10103 named idr0, and then sets the dma timeout might look like: #define DMATIMEOUT 120 /* 120 seconds */ ... int filedes ; char devname[31] ; u_long arg[16] ; ... strcpy(devname,"/dev/idr0\0") ; filedes = open(devname,O_RDWR) ; ... arg[0] = DMATIMEOUT ; ioctl(filedes,IDRIO_SET_DMA_TIME,arg) ; All of the ioctl() calls conform to this general example. What follows is a description of each command, and the possible arguments used with that command. In the argument descriptions for each command, including a particular argument in arg[0] is equivalent to setting it to one. Omitting is is equivalent to setting it to zero. IDRIO_SET_MODE Sets the bits of the 10103 mode register. This is generally used once - if at all - at the beginning of a program to configure the 10103's "static" parameters, which will not change during this use of the board. This register is set to all 0s at power-up, but is not cleared by the MCLR pulse. The possible arg values may be or'd together: IDR_RDYT If 0, READY goes true during BUSY. If 1, READY goes true at BUSY trailing edge. READY true during BUSY is the normal mode for DR11-W applications. IDR_FMOD This bit controls the depth and speed of the input fifo. If 0, input can be done at approximately 8Mbytes/second, and half of the fifo will be used. If 1, the entire fifo is available, but the input transfer rate is limited to approximately 6.6Mbytes/second. This bit should probably be set to 1 for those applications that use a relatively low speed data stream that is continuous over several unix read() calls. This will help prevent the fifo from overflowing between reads. Consult IKON for information on available fifo depths. (The default is 512 bytes). IDR_BDIS A one here disables the CYCLE RQ B input. Used if for some reason the device connected to the 10103 floats this input. IDR_SWAP A one causes DVMA bytes to and from the attached device to be swapped within a 16 bit DR11 word. Does not affect the 10103 registers, only device data. IDR_CRQP 0 causes the CYCLE RQ A & B inputs to be rising edge active. 1 selects falling edge active. Rising edge active is normal for DR11-W applications. IDR_BSYP 0 selects the BUSY output to be asserted low, 1 selects asserted high. Asserted low is normal for interprocessor links to another DR11. An attached device may require either high or low assertions, depending on how it is designed. IDR_SPEED_0, IDR_SPEED_1, IDR_SPEED_2, IDR_SPEED_3 One of these arguments may be used to select the speed of the DR11 handshake with the attached device. This choice affects the input data de-skew, the output data settling time, and the length of BUSY. Speed 0 is the fastest selection. See the 10103 manual. A call to set the mode to byte swapping, and the slowest speed would be: arg[0] = IDR_SWAP | IDR_SPEED_3 ; ioctl(filedes,IDRIO_SET_MODE,arg) ; IDRIO_IMM_FCN This call sets the outgoing function bits to the requested value immediately. The desired function bit combinations are very application dependent, although they usually have a fixed meaning in interprocessor links. In links, FCN1 on means that the local DR11 is to be the receiver of the transfer, FCN3 is always set to 1 during the DMA block transfer, and FCN2 can be used to pulse the other DR11's ATTENTION input (the ACF2 pulse can be used to do this automatically, which avoids having to use this comand once to set FCN2 and again to reset it). IDR_FCN3, IDR_FCN2, IDR_FCN1 These arguments may be or'd together. IDRIO_READ_FCN, IDRIO_WRITE_FCN These calls pre-define the function bit patterns to be set at the start of a read or write operation. They have no effect until the read or write is actually issued. It is only necessary to make one or both of these calls once if at all. After being initially set, they will apply to all later reads and/or writes. The arguments used are the same as for IDRIO_IMM_FCN. There are pre-defined defaults for the function bits that may be changed by editing the idrio.h file. See a later section of these notes for further information. IDRIO_IMM_PULSE This call issues certain pulses to the attached device and to the 10103 logic. Some of the available pulses affect the internal operation of the 10103, and should be used with caution! The internal pulses are IDR_REOR, _RATN, _TERM, and _MCLR. Most of these pulses will be set using the read and write deferred pulse calls. The IDR_ACF2 pulse is the only one likely to be used as an immediate pulse, unless operating in MANUAL mode. The arguments to this command may be or'd together. IDR_REOR Clears the internal DR11 range counter end of range flag. IDR_RATN Clears teh internal ATTENTION flag. IDR_TERM Sets READY true. Can be used to terminate a DR11 block transfer that was started in MANUAL mode. Not necessary when operating in AUTO mode. (See later for descriptions of these modes). IDR_MCLR Clears all 10103 logic. Use with extreme caution!!!! Better yet, don't use it at all!!!!!!! IDR_INIT Sends an INITAILIZE pulse to the attached device. Has no effect on the 10103. IDR_ACF2 Pulses the ACLO_FNCT2 output. In interprocessor links, this will cause an ATTENTION pulse at the other end of the link. Typically used for preliminary handshaking and synchronization prior to transferring a DMA block. IDR_CYCL Forces an immediate cycle request. This simulates a cycle request from the attached device. It is normally used to start a link-mode output transfer. It is generally NOT used to start input in any application. There are some non-link applications that will use it to start output transfers. These are situations where the attached device does not issue the first cycle request at the beginnig of a transfer, but does issue all subsequent requests. IDR_GO Issues a GO pulse to the attached device. The GO indicates that DMA block transfers may begin. IDRIO_READ_PULSE, IDRIO_WRITE_PULSE These calls set the pulse commands to be issued at the start of a read or write. They need to be set only once. There are pre-defined defaults for the read and write pulses. Typically, (IDR_GO | IDR_CYCLE) would be used at the beginning of a link mode write. (IDR_GO | IDR_ACF2) would be used at the start of a link mode read. GO enables the block transfer, CYCLE forces the first word of the transfer for output transfers, and ACF2 indicates to the other end of the link that this board is ready to receive data for input transfers. IDRIO_SET_DMA_TIME, IDRIO_SET_ATTN_TIME, IDRIO_SET_RDY_TIME These calls set the timeout values (in seconds) used during a wait for the end of a DMA block transfer, wait for ATTENTION, and wait for READY to go true. Currently, the pre-defined defaults are 30 seconds for each of these parameters. In addition, the ioctl() code will not let the calling program set the timeout(s) to less than 10 seconds, or more than 10 minutes. This is left over from an earlier version of the driver that couldn't receive signals while waiting. The defaults, and/or the limits, can be changed by editing the idrio.h file. IDRIO_ATTN_WAIT, IDRIO_RDY_WAIT These calls can be used to wait (by sleeping if necessary) for ATTENTION, or READY, respectively. The sleeps are subject to the above timeout values. ATTN_WAIT is typically used when waiting for an attention pulse from the attached device, or other DR11. In an interprocessor link, ATTENTION is often used to synchronize the start of a DMA block transfer. See interprocessor links in the 10103 manual. RDY_WAIT is usually used in MANUAL mode. If multiple unix reads or writes are used to satisfy a larger DR11 range count, this wait can be used to test for DR11 end of range - or termination of a block transfer by ATTENTION (which sets READY). IDRIO_GET_STATUS This call can be used to read the 10103's Flags/Status register. It may be useful when polling for certain device or 10103 conditions. Any or all of these conditions/flags may be true at the same time. IDR_EORF This flag sets when the DR11 range counter underflows. IDR_ATTF Sets at the rising edge of an incoming ATTENTION pulse. IDR_ATTN This flag follows the state of the ATTENTION input. Note that GO has no effect on the 10103 if ATTENTION is true when GO is issued. This bit can be used to make sure that ATTENTION is off prior to issuing GO in MANUAL mode. In AUTO mode, this is taken care of by the driver code. IDR_MCER This is an error flag that sets if the attached device requests a transfer while the 10103 is busy processing the previous transfer request. (CYCLE RQ while BUSY is true). In normal transfers that use a full handshake - such as interprocessor link transfers - this bit will never set. It is useful for applications that must use a continuous input clock to drive CYCLE RQ. In this case, the 10103 must always be fast enough to process each request in the time between clocks, and more important, must always have room in its fifo. The 10103 is extremely fast. However, in MANUAL mode, the fifo will continue to fill in the gap between reads. In this case, it is possible to overflow the fifo if the system takes too long to start the next read. The MCER flag will alert the user to this error if tested after each unix read call. This flag does not cause an interrupt or affect the transfer in any way. It is a status flag only. IDR_STTA, IDR_STTB, IDR_STTC These follow the status A, B, and C inputs from the attached device. They have no effect on the 10103 logic. IDR_REDY This is the master READY bit in the 10103. It goes to 0 when GO is issued, and set to 1 when the DR11 range count is exhausted, ATTENTION is received, or TERM or MCLR is pulsed. IDRIO_GET_RANGE This call returns the DR11 range counter residual value. It is returned as the 24 least significant bits of an unsigned integer. It is equal to the remaining transfer count MINUS ONE. At the end of a complete block, the value returned will be 0x00FFFFFF. This call may be useful in MANUAL mode when doing an input of a word count less than the requested block size. Some applications may involve a variable block size. The range count may be set to the maximum allowed - or desired - and read after the transfer to determine the number of words actaully received. It may be necessary to use this count to determine how many unix read calls are necessary to input to memory the data actually received. IDRIO_GET_REGS This ioctl command returns all 11 of the board's registers in an arg array of unsigned integers. The DMAIO registers are 32 bits wide. The DR11 registers are returned in the least significant bytes of the integers. See the 10103 manual for complete register descriptions. The organization of the returned array is: arg[0] DMAIO CSR DMA controller COMMAND/STATUS register arg[1] DMAIO ADD DMA controller ADDRESS register arg[2] DMAIO RANGE DMA controller RANGE (byte) counter arg[3] DR11 MODE DR11 MODE register arg[4] DR11 LATCHED FCN DR11 LATCHED FUNCTIONS register arg[5] DR11 FLAGS/STATUS DR11 FLAGS/STATUS register arg[6] DR11 DATA HIGH DR11 DATA from device - high 8 bits arg[7] DR11 DATA LOW DR11 DATA from device - low 8 bits arg[8] DR11 RANGE HIGH DR11 RANGE register - high 8 bits arg[9] DR11 RANGE MID DR11 RANGE register - middle 8 bits arg[10] DR11 RANGE LOW DR11 RANGE register - low 8 bits IDRIO_GET_FLAGS Returns various driver software flags and error bits. This is primarily diagnostic. IDR_DVMA_WAIT waiting for DVMA terminal count IDR_EOR_WAIT waiting for DR11 end of range IDR_ATTN_WAIT waiting for ATTENTION IDR_RDY_WAIT waiting for READY IDR_DVMA_TIMEOUT DVMA wait timeout IDR_EOR_TIMEOUT EOR wait timeout IDR_ATTN_TIMEOUT ATTENTION wait timeout IDR_RDY_TIMEOUT READY wait timeout IDR_MANUAL manual mode IDR_INPUT input mode IDR_MCYL_ERR multicycle error IDR_SIG_RECEIVED signal received IDRIO_DATA_OUT Sends a 16 bit value to the attached device. This is a programmed i/o output, and does not use any of the DVMA handshake signals (GO, BUSY, etc). ACF2 and ATTENTION pulses are often used for software synchronization of p-i/o data transfer. The data sent can be anything useful to the user. For instance, it could be the requested transfer count in an interprocessor link, or command bits to a display or data collection device. IDRIO_DATA_IN Reads the 16 bit value from the DR11 input data lines. IDRIO_SET_RANGE Sets the DR11 range counter to an initial value. This value is must be the desired WORD count MINUS 1. This call is only used in MANUAL mode. The maximum value allowed is 0xFFFFFF, which gives a maximum DR11 block size of 32Mbytes. IDRIO_AUTO, IDRIO_MANUAL These calls determine the overall operating mode of the 10103 driver. In AUTO mode, each call to the idr_strategy routine (made via unix read or write calls), is treated as a complete transfer. The DR11 and DVMA range couters are initialized to equivalent counts, and the appropriate read or write pulses and function bits are set. The driver sleeps until the counts are exhausted, or an ATTENTION is received. Note that this is done for each strategy call, not for each read or write call. If read or write is called with a block size to big for a single strategy call (as determined by the system's minphys parameter, and available DVMA space) mulitple calls may be made invisibly to the user, causing multiple read or write pulse operations to be performed. AUTO mode operation takes care of the DR11 range counter, and performs all the necessary set-up tasks and waits to complete the read or write. AUTO mode is the default. MANUAL mode may be selected for cases when multiple read or write calls will be used explicitly to satisfy a larger DR11 block size - or for the case of continuous data transfers where data must be transferred to or from disk without terminating the overall DR11 block. In MANUAL mode, unix read or write calls only communicate with the 10103's DVMA logic. The user must set the DR11 range counter, issue all necessary function bit changes and pulses, and wait for DR11 block completion - if desired. The calling program must also use the START_READ and START_WRITE calls prior to issuing GO to start the overall block, and prior to issuing the first unix read or write call within the block. The BLOCK_END call must be used after all DR11 transfers are complete, typically after a wait for READY (for output) or after the last read (for input). IDRIO_START_READ, IDRIO_START_WRTITE, IDRIO_BLOCK_END See the description of MANUAL mode, above. 10103 DRIVER DEFAULT PARAMETERS There are several default driver parameters that are determined at compile time. They can typically be overriden by explicit ioctl() calls to the driver. There may be occasional applications that must function without ioctl calls - for example, if the application used cat, or some other pre-existing program - and there was no convenient place to insert the necessary calls. The defaults shown below may be changed by editing the idrio.h file, and re making the driver (make -f idr.mak). #define DMA_TIME_DEF 30 /* all timeout defaults are in seconds */ #define ATTN_TIME_DEF 30 #define RDY_TIME_DEF 30 #define DMA_TIME_MAX 600 /* the caller is limited to 10 minutes */ #define ATTN_TIME_MAX 600 /* to prevent long hangs - this is not */ #define RDY_TIME_MAX 600 /* really necessary in this version */ #define DMA_TIME_MIN 10 /* we don't want to time out in the */ #define ATTN_TIME_MIN 10 /* middle of active DMA!! */ #define RDY_TIME_MIN 10 #define MODE_REG_DEF 0 /* mode register defaults to all 0 */ #define LATCH_REG_DEF 0 /* as does the latched function register*/ #define READ_FCN_DEF (IDR_FCN1 | IDR_FCN3) /* link style: input and*/ /* fcn3 on for block */ #define READ_PULSE_DEF IDR_GO /* GO only. link also needs IDR_ACF2 */ #define WRITE_FCN_DEF IDR_FCN3 /* link style */ #define WRITE_PULSE_DEF (IDR_CYCL | IDR_GO) /* pulse GO and CYCLE */