VxWorks Reference Manual : Libraries
sym895Lib - SCSI-2 driver for Symbios SYM895 SCSI Controller.
sym895CtrlCreate( ) - create a structure for a SYM895 device.
sym895CtrlInit( ) - initialize a SCSI Controller Structure.
sym895HwInit( ) - hardware initialization for the 895 Chip.
sym895SetHwOptions( ) - sets the Sym895 chip Options.
sym895Intr( ) - interrupt service routine for the SCSI Controller.
sym895Show( ) - display values of all readable SYM 53C8xx SIOP registers.
sym895GPIOConfig( ) - configures general purpose pins GPIO 0-4.
sym895GPIOCtrl( ) - controls general purpose pins GPIO 0-4.
sym895Loopback( ) - This routine performs loopback diagnotics on 895 chip.
The SYM53C895 PCI-SCSI I/O Processor (SIOP) brings Ultra2 SCSI performance to Host adapter, making it easy to add a high performance SCSI Bus to any PCI System. It supports Ultra-2 SCSI rates and allows increased SCSI connectivity and cable length Low Voltage Differential (LVD) signaling for SCSI. This driver runs in conjunction with SCRIPTS Assembly program for the Symbios SCSI controllers. These scripts use DMA transfers for all data, messages, and status transfers.
For each controller device a manager task is created to manage SCSI threads on each bus. A SCSI thread represents each unit of SCSI work.
This driver supports multiple initiators, disconnect/reconnect, tagged command queuing and synchronous data transfer protocol. In general, the SCSI system and this driver will automatically choose the best combination of these features to suit the target devices used. However, the default choices may be over-ridden by using the function "scsiTargetOptionsSet( )" (see scsiLib).
Scatter/ Gather memory support: Scatter-Gather transfers are used when data scattered across memory must be transferred across the SCSI bus together with out CPU intervention. This is achieved by a chain of block move script instructions together with the support from the driver. The driver is expected to provide a set of addresses and byte counts for the SCRIPTS code. However there is no support as such from vxworks SCSI Manager for this kind of data transfers. So the implementation, as of today, is not completely integrated with vxworks, and assumes support from SCSI manager in the form of array of pointers. The macro SCATTER_GATHER in sym895.h is thus not defined to avoid compilation errors.
Loopback mode allows 895 chip to control all SCSI signals, regardless of whether it is in initiator or target role. This mode insures proper SCRIPTS instructions fetches and data paths. SYM895 executes initiator instructions through the SCRIPTS, and the target role is implemented in sym895Loopback by asserting and polling the appropriate SCSI signals in the SOCL, SODL, SBCL, and SBDL registers.
Most of the routines in this driver are accessible only through the I/O system. Three routines, however, must be called directly sym895CtrlCreate( ) to create a controller structure, and sym895CtrlInit( ) to initialize it. If the default configuration is not correct, the routine sym895SetHwRegister( ) must be used to properly configure the registers.
Critical events, which are to be logged anyway irrespective of whether debugging is being done or not, can be logged by using the SCSI_MSG macro.
The global variable sym895PciMemOffset was created to provide the BSP with a means of changing the VIRT_TO_PHYS mapping without changing the functions in the cacheFuncs structures. In generating physical addresses for DMA on the PCI bus, local addresses are passed through the function CACHE_DMA_VIRT_TO_PHYS and then the value of sym895PciMemOffset is added. For backward compatibility, the initial value of sym895PciMemOffset comes from the macro PCI_TO_MEM_OFFSET.
The BSP must connect the interrupt service routine for the controller device to the appropriate interrupt system. The routine to be called is sym895Intr( ), and the argument is the pointer to the controller device pSiop. i.e.
pSiop = sym895CtrlCreate (...); intConnect (XXXX, sym895Intr, pSiop); sym895CtrlInit (pSiop, ...);
All hardware access is to be done through macros. The default definition of the SYM895_REGx_READ( ) and SYM895_REGx_WRITE( ) macros (where x stands for the width of the register being accessed ) assumes an I/O mapped model. Register access mode can be set to either IO/memory using SYM895_IO_MAPPED macro in sym895.h. The macros can be redefined as necessary to accommodate other models, and situations where timing and write pipe considerations need to be addressed. In IO mapped mode, BSP routines sysInByte( ), sysOutByte( ) are used for accessing SYM895 registers. If these standard calls are not supported, the calls supported by respective BSP are to be mapped to these standard calls. Memory mapped mode makes use of pointers to register offsets.
The macro SYM895_REGx_READ(pDev, reg) is used to read a register of width x bits. The two arguments are the device structure pointer and the register offset.
The macro SYM895_REGx_WRITE(pDev, reg,data) is used to write data to the specified register address. These macros presume memory mapped I/O by default. Both macros can be redefined to tailor the driver to some other I/O model.
scsiLib.h, sym895.h, and sym895Script.c
SEE ALSO scsiLib, scsi2Lib, cacheLib, SYM53C895 PCI-SCSI I/O Processor Data Manual Version 3.0, Symbios Logic PCI-SCSI I/O Processors Programming Guide Version 2.1,
sym895CtrlCreate( ) - create a structure for a SYM895 device.
SYM895_SCSI_CTRL * sym895CtrlCreate ( UINT8 * siopBaseAdrs, /* base address of the SCSI Controller */ UINT clkPeriod, /* clock controller period (nsec* 100) */ UINT16 devType, /* SCSI device type */ UINT8 * siopRamBaseAdrs, /* on Chip Ram Address */ UINT16 flags /* options */ )
This routine creates a SCSI Controller data structure and must be called before using a SCSI Controller chip. It should be called once and only once for a specified SCSI Controller. Since it allocates memory for a structure needed by all routines in sym895Lib, it must be called before any other routines in the library. After calling this routine, sym895CtrlInit( ) should be called at least once before any SCSI transactions are initiated using the SCSI Controller.
A Detailed description of parameters follows.
- siopBaseAdrs
- base address of the SCSI controller.
- clkPeriod
- clock controller period (nsec*100).This is used to determine the clock period for the SCSI core and affects the timing of both asynchronous and synchronous transfers. Several Commonly used values are
SYM895_1667MHZ 6000 16.67Mhz chip SYM895_20MHZ 5000 20Mhz chip SYM895_25MHZ 4000 25Mhz chip SYM895_3750MHZ 2667 37.50Mhz chip SYM895_40MHZ 2500 40Mhz chip SYM895_50MHZ 2000 50Mhz chip SYM895_66MHZ 1515 66Mhz chip SYM895_6666MHZ 1500 66Mhz chip SYM895_75MHZ 1333 75Mhz chip SYM895_80MHZ 1250 80Mhz chip SYM895_160MHZ 625 40Mhz chip with Quadrupler
- devType
- SCSI sym8xx device type
- siopRamBaseAdrs
- base address of the internal scripts RAM
- flags
- various device/debug options for the driver. Commonly used values are
SYM895_ENABLE_PARITY_CHECK 0x01 SYM895_ENABLE_SINGLE_STEP 0x02 SYM895_COPY_SCRIPTS 0x04
A pointer to SYM895_SCSI_CTRL structure, or NULL if memory is unavailable or there are invalid parameters.
N/A
sym895CtrlInit( ) - initialize a SCSI Controller Structure.
STATUS sym895CtrlInit ( SIOP * pSiop, /* pointer to SCSI Controller structure */ UINT scsiCtrlBusId /* SCSI bus ID of this SCSI Controller */ )
This routine initializes an SCSI Controller structure, after the structure is created with sym895CtrlCreate( ). This structure must be initialized before the SCSI Controller can be used. It may be called more than once if needed; however, it should only be called while there is no activity on the SCSI interface.
A Detailed description of parameters follows.
- pSiop
- pointer to the SCSI controller structure created with sym895CtrlCreate( )
- scsiCtrlBusId
- SCSI Bus Id of the SIOP.
RETURNS OK, or ERROR if parameters are out of range.
N/A
sym895HwInit( ) - hardware initialization for the 895 Chip.
STATUS sym895HwInit ( SIOP * pSiop /* pointer to the SIOP structure */ )
This function puts the SIOP in a known quiescent state. Also, if copying of SCSI scripts is enabled, this routine copies entire SCRIPTS code from host memory to On-Chip SCRIPTS RAM. This routine does not modify any of the registers that are set by sym895SetHwOptions( ).
For details of the register bits initialised here, refer to SYM53C895 data manual Version 3.0.
- pSiop
- pointer to the SIOP structure
OK, or ERROR if parameters are out of range.
N/A
sym895SetHwOptions( ) - sets the Sym895 chip Options.
STATUS sym895SetHwOptions ( SIOP * pSiop, /* pointer to the SIOP structure */ SYM895_HW_OPTIONS * pHwOptions /* pointer to the Options Structure */ )
This function sets optional bits required for tweaking the performance of 895 to the Ultra2 SCSI. The routine should be called with SYM895_HW_OPTIONS structure as defined in sym895.h file.
The input parameters are
- pSiop
- pointer to the SIOP structure
- pHwOptions
- pointer to the a SYM895_HW_OPTIONS structure.
struct sym895HWOptions { int SCLK : 1; /* STEST1:b7,if false, uses PCI Clock for SCSI */ int SCE : 1; /* STEST2:b7, enable assertion of SCSI thro SOCL*/ /* and SODL registers */ int DIF : 1; /* STEST2:b5, enable differential SCSI */ int AWS : 1; /* STEST2:b2, Always Wide SCSI */ int EWS : 1; /* SCNTL3:b3, Enable Wide SCSI */ int EXT : 1; /* STEST2:b1, Extend SREQ/SACK filtering */ int TE : 1; /* STEST3:b7, TolerANT Enable */ int BL : 3; /* DMODE:b7,b6, CTEST5:b2 : Burst length */ /* when set to any of 32/64/128 burst length */ /* transfers, requires the DMA Fifo size to be */ /* 816 bytes (ctest5:b5 = 1). */ int SIOM : 1; /* DMODE:b5, Source I/O Memory Enable */ int DIOM : 1; /* DMODE:b4, Destination I/O Memory Enable */ int EXC : 1; /* SCNTL1:b7, Slow Cable Mode */ int ULTRA : 1; /* SCNTL3:b7, Ultra Enable */ int DFS : 1; /* CTEST5:b5, DMA Fifo size 112/816 bytes */ } SYM895_HW_OPTIONS;This routine should not be called when there is SCSI Bus Activity as this modifies the SIOP Registers.
OK or ERROR if any of the input parameters is not valid.
N/A
sym895Lib, sym895.h, sym895CtrlCreate( )
sym895Intr( ) - interrupt service routine for the SCSI Controller.
void sym895Intr ( SIOP * pSiop /* pointer to the SIOP structure */ )
The first thing to determine is whether the device is generating an interrupt If not, then this routine must exit as quickly as possible.
Find the event type corresponding to this interrupt, and carry out any actions which must be done before the SCSI Controller is re-started. Determine whether or not the SCSI Controller is connected to the bus (depending on the event type - see note below). If not, start a client script if possible or else just make the SCSI Controller wait for something else to happen.
The "connected" variable, at the end of switch statement, reflects the status of the currently executing thread. If it is TRUE it means that the thread is suspended and must be processed at the task level. Set the state of SIOP to IDLE and leave the control to the SCSI Manager. The SCSI Manager, in turn invokes the driver through a "resume" call.
Notify the SCSI manager of a controller event.
RETURNS N/A
sym895Show( ) - display values of all readable SYM 53C8xx SIOP registers.
STATUS sym895Show ( SIOP * pSiop /* pointer to SCSI controller */ )
This routine displays the state of the SIOP registers in a user-friendly way. It is useful primarily for debugging. The input parameter is the pointer to the SIOP information structure returned by the sym895CtrlCreate( ) call.
The only readable register during a script execution is the Istat register. If you use this routine during the execution of a SCSI command, the result could be unpredictable.
-> sym895Show SYM895 Registers ---------------- Scntl0 = 0xd0 Scntl1 = 0x00 Scntl2 = 0x00 Scntl3 = 0x00 Scid = 0x67 Sxfer = 0x00 Sdid = 0x00 Gpreg = 0x0f Sfbr = 0x0f Socl = 0x00 Ssid = 0x00 Sbcl = 0x00 Dstat = 0x80 Sstat0 = 0x00 Sstat1 = 0x0f Sstat2 = 0x02 Dsa = 0x07ea9538 Istat = 0x00 Ctest0 = 0x00 Ctest1 = 0xf0 Ctest2 = 0x35 Ctest3 = 0x10 Temp = 0x001d0c54 Dfifo = 0x00 Dbc0:23-Dcmd24:31 = 0x54000000 Dnad = 0x001d0c5c Dsp = 0x001d0c5c Dsps = 0x000000a0 Scratch0 = 0x01 Scratch1 = 0x00 Scratch2 = 0x00 Scratch3 = 0x00 Dmode = 0x81 Dien = 0x35 Dwt = 0x00 Dcntl = 0x01 Sien0 = 0x0f Sien1 = 0x17 Sist0 = 0x00 Sist1 = 0x00 Slpar = 0x4c Swide = 0x00 Macntl = 0xd0 Gpcntl = 0x0f Stime0 = 0x00 Stime1 = 0x00 Respid0 = 0x80 Respid1 = 0x00 Stest0 = 0x07 Stest1 = 0x00 Stest2 = 0x00 Stest3 = 0x80 Sidl = 0x0000 Sodl = 0x0000 Sbdl = 0x0000 Scratchb = 0x00000200 value = 0 = 0x0
OK, or ERROR if pScsiCtrl and pSysScsiCtrl are both NULL.
sym895Lib, sym895CtrlCreate( )
sym895GPIOConfig( ) - configures general purpose pins GPIO 0-4.
STATUS sym895GPIOConfig ( SIOP * pSiop, /* pointer to SIOP structure */ UINT8 ioEnable, /* bits indicate input/output */ UINT8 mask /* mask for ioEnable parameter */ )
This routine uses the GPCNTL register to configure the general purpose pins available on Sym895 chip. Bits 0-4 of GPCNTL register map to GPIO 0-4 pins. A bit set in GPCNTL configures corresponding pin as input and a bit reset configures the pins as output.
- pSiop
pointer to the SIOP structure.
- ioEnable
bits 0-4 of this parameter configure GPIO 0-4 pins. 1 => input, 0 => output.
- mask
- bits 0-4 of this parameter identify valid bits in ioEnable parameter. Only
those pins are configured, which have a corresonding bit set in this parameter.
sym895GPIOCtrl( ) - controls general purpose pins GPIO 0-4.
STATUS sym895GPIOCtrl ( SIOP * pSiop, /* pointer to SIOP structure */ UINT8 ioState, /* bits indicate set/reset */ UINT8 mask /* mask for ioState parameter */ )
This routine uses the GPREG register to set/reset of the general purpose pins available on Sym895 chip.
- pSiop
pointer to the SIOP structure.
- ioState
bits 0-4 of this parameter controls GPIO 0-4 pins. 1 => set, 0 => reset.
- mask
- bits 0-4 of this parameter identify valid bits in ioState parameter. Only
those pins are activated, which have a corresonding bit set in this parameter.
sym895Loopback( ) - This routine performs loopback diagnotics on 895 chip.
STATUS sym895Loopback ( SIOP * pSiop /* pointer to SIOP controller structure */ )
Loopback mode allows 895 chip to control all signals, regardless of whether it is in initiator or target role. This mode insures proper SCRIPTS instruction fetches and data paths. SYM895 executes initiator instructions through the SCRIPTS, and this routine implements the target role by asserting and polling the appropriate SCSI signals in the SOCL, SODL, SBCL, and SBDL registers.
To configure 895 in loopback mode,
(1) Bits 3 and 4 of STEST2 should be set to put SCSI pins in High-Impedance
mode, so that signals are not asserted on to the SCSI bus.(2) Bit 4 of DCNTL should be set to turn on single step mode. This allows the
target program (this routine) to monitor when an initiator SCRIPTS
instruction has completed.In this routine, SELECTION, MSG_OUT and DATA_OUT phases are checked. This will ensure that data and control paths are proper.