tekdxfxsl FibreXtreme I/O Interface

Transcription

1 RACEway/RACE++ I/O Controllers tekdxfxsl FibreXtreme I/O Interface User s Manual TEK/TM February 2002

2 TEK Microsystems has made every effort to ensure that this document is accurate and complete. However, TEK reserves the right to make changes and improvements to the products described in this document at any time and without notice. This product is covered by a limited warranty that is described in the manual. Other than the stated limited warranty, TEK disclaims all other warranties, including the warranties of merchantability and of fitness for a particular purpose. In the event of a failure of the hardware or software described in this document, TEK s obligation is limited to repair or replacement of the defective item, or, if the item cannot be repaired or replaced, a refund of the purchase price for the item. TEK assumes no liability arising out of the application or use of the hardware or software, and assumes no responsibility for direct, indirect, incidental or consequential damages of any kind. The electronic equipment described in this document generates, uses, and can radiate radio frequency energy. Operation of this equipment in a residential area is likely to cause radio interference, in which case the user, at his own expense, will be required to take whatever measures may be required to correct the interference. TEK Microsystems products are not authorized for use as critical components in life support devices or systems without the express written agreement of an officer of TEK Microsystems. This document is Copyright , TEK Microsystems, Incorporated. All Rights Reserved. PowerRACE and tekdx are trademarks of TEK Microsystems, Incorporated. RACE, RACE++ and MC/OS are trademarks of Mercury Computer Systems, Inc. FibreXtreme is a trademark of Systran Corporation. VxWorks and Tornado are registered trademarks of Wind River Software, Inc. Other trademarks used are owned by their respective manufacturers. Document ordering code and release information: TEK/TM February 2002

3 Table of Contents Introduction...1 System Requirements...1 Supported Modules...1 Installation...2 Client Installation...2 Server Installation...2 Hardware Installation...2 Known Limitations...3 Client Functions...4 Open/Close Functions...5 tekdxfxslopen( )...6 tekdxfxslclose( )...7 Information Functions...8 tekdxfxslgetmoduleid( )...9 tekdxfxslgetdriverid( )...10 tekdxfxslgetmoduleinfo( )...11 Configuration Functions...12 tekdxfxslrxgetparms( )...13 tekdxfxslrxsetparms( )...14 tekdxfxsltxgetparms( )...15 tekdxfxsltxsetparms( )...16 Device Configurations...17 Systran FibreXtreme SL Systran FibreXtreme SL

4 Introduction This document describes the configuration and use of the tekdxfxsl client-server software for implementing streaming VITA 17.1 FibreXtreme I/O interfaces in RACEway and RACE++ systems. System Requirements The tekdxfxsl client software requires the following environment: Mercury PowerPC running MC/OS. The tekdxfxsl server software requires the following environment: PowerRACE-1 or 2 controller card. Supported Modules The tekdxfxsl software supports the following PMC modules: Systran FibreXtreme SL100 Data Link PMC Systran FibreXtreme SL240 Data Link PMC Page 1

5 Installation The tekdxfxsl software consists of two separate software modules: The client software is a library of callable functions that are linked with the user application and executed on the client. The server software is a VxWorks program that is installed on a PowerRACE I/O controller card. In addition to the installation of the software, the user must also install the PowerRACE card into the target system and add the PowerRACE card into the configuration file used by MC/OS to identify hardware elements of the system. Each phase of installation is described below. Client Installation The tekdxfxsl client software consists of an object library and associated header files that are copied to the MC/OS directories on the development host. The user application can perform tekdxfxsl calls by #include ing the tekdx.h and tekdxfxsl.h header files and linking the object library with the user application. Server Installation The tekdxfxsl server firmware consists of a binary image that is installed in FLASH memory on the PowerRACE card. The procedure for software installation is described in the PowerRACE User s Manual. Hardware Installation The PowerRACE card that is being used as a tekdx server consists of a number of RACEway nodes and an onboard RACEway crossbar. Some of the RACEway nodes provide memory buffers and some of the RACEway nodes provide the tekdx servers. Each processor is an independent tekdx server. In the MC/OS configuration database, the PowerRACE card is defined as several raw RACEway nodes, each of which is given a user-assigned name. The name of the tekdx processor node is the name that is used when opening a tekdx connection to a server. Page 2

6 Known Limitations The current implementation has the following limitations: The server-side software does not properly handle multiple attach requests. The user must ensure that only one CE and process is attached to the server at a time. Please review the README and CHANGES files in the software distribution for more up-to-date information about the current software release. Page 3

7 Client Functions The tekdxfxsl client software is a software layer that is built on top of the tekdx client-server software architecture. All of the tekdxfxsl software functions are essentially simplified versions of underlying tekdx calls. The user application can use tekdxfxsl routines, or can simply use the underlying tekdx calls directly. Using the tekdxfxsl interface involves a number of tradeoffs of performance vs. portability: The tekdx API is more portable than tekdxfxsl for different types of I/O interface hardware. If the user application is written in terms of tekdx calls alone, the application will require very little modification to move from one I/O device to another (i.e. HOTLink to FibreChannel, for example). The tekdxfxsl API provides more type checking and better access to FXSL-specific data structures. For some configuration operations, FXSL-specific data structures are required and the tekdxfxsl interface provides a more controlled interface to those data structures (i.e. tekdxfxslrxgetparms( ), which takes a pointer to a TEKDX_FXSL_PARMS structure instead of a tekdx_dev_control( ) call which takes a typeless pointer). The tekdxfxsl functions add a very small amount of processing time due to the extra function call layer. All of the tekdxfxsl functions are associated with configuration and setup operations. To keep the actual data transfer as generic and high performance as possible, data transfer is accomplished using the standard tekdx functions: typically, tekdx_create( ), tekdx_copy( ) and tekdx_start( ). The tekdxfxsl functions are divided into the following groups: Open/close. These functions open and close tekdx streams between the client node and the tekdx server where the FXSL device resides. Information functions. These functions provide mechanisms for the client to determine the type and model of hardware and software installed on the tekdx server. Configuration functions. These functions provide the ability to get and set the hardware configuration parameters of the FXSL device. Each group of functions is described in the following sections. Page 4

8 Open/Close Functions The tekdxfxsl client software provides functions to open and close the tekdx stream associated with a specific FXSL device. The open/close functions are: tekdxfxslopen. This function opens an I/O stream to the FXSL device. tekdxfxslclose. This function closes an I/O stream to the FXSL device. The tekdx stream must be opened prior to performing any other operations on the stream. Once the stream is opened, the user may retrieve information about the installed hardware and software, configure the FXSL device, and transfer data between RACEway Shared Memory Buffers (SMBs) and the FXSL device. When all operations are completed, the user software should close the tekdx stream. After the stream is closed, no further tekdx operations are valid until the stream is reopened. These functions are described in more detail below. Page 5

9 tekdxfxslopen( ) NAME tekdxfxslopen( ) Open a tekdx stream to a FXSL device. SYNOPSIS long tekdxfxslopen ( const char *devname, TEKDX_handle *dxp ); DESCRIPTION This function creates a connection to a FXSL hardware device managed by the tekdx server specified by devname. The devname argument consists of two parts, separated by a :. The first part, which is mandatory, specifies the name of the tekdx server node in the MC/OS configuration file. The second part, which is optional, specifies the device to be opened. For the tekdxfxsl server, the default device name is fxsl. This routine performs a tekdx_dev_attach( ) followed by a tekdx_dev_open( ). If successful, a handle to the tekdx stream is returned in *dxp. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_attach( ), tekdx_dev_open( ) CAUTIONS The current implementation does not properly handle multiple connections to a single server. Page 6

10 tekdxfxslclose( ) NAME tekdxfxslclose( ) Close the tekdx stream. SYNOPSIS long tekdxfxslclose ( TEKDX_handle dx ); DESCRIPTION This routine closes the tekdx stream specified by dx and detaches the client from the tekdx server. The semantics of closing a tekdx stream are device-dependent. For all tekdx devices, the server is required to ensure that all queued data is flushed out to the device. Additional processing may be performed for specific devices. This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_close( ) followed by tekdx_dev_detach( ). In the current release, the calling task is responsible for recovering memory and other resources that have been allocated through lower-level tekdx calls (i.e. tekdx_copy, tekdx_group). Future releases are expected to automate the cleanup process. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_close( ), tekdx_dev_detach( ) CAUTIONS This routine should not be invoked if data transfers are currently in progress. Page 7

11 Information Functions The tekdxfxsl client software provides functions to retrieve configuration and identification information about the tekdx server, hardware driver software, and the installed hardware module. The information functions are: tekdxfxslgetmoduleid. This function retrieves the FXSL hardware module identification information (i.e., the type of module installed). This is always SL240 in this release because there is currently no way to distinguish between the SL100 and SL240 modules. tekdxfxslgetdriverid. This function retrieves the FXSL server/driver version information. It is returned as a string in x.y.z format (e.g., ). tekdxfxslgetmoduleinfo. This function retrieves the FXSL module information. The low-level Systran driver does not provide anything useful about the hardware module, so the module information structure contains only a placeholder. These functions are described in more detail below. Page 8

12 tekdxfxslgetmoduleid( ) NAME tekdxfxslgetmoduleid( ) Get module ID string. SYNOPSIS long tekdxfxslgetmoduleid ( TEKDX_handle dx, char *buf, int maxlen ); DESCRIPTION This function retrieves the hardware module identification information for the tekdx stream specified by dx. The module ID information is copied into the string buffer at *buf with a maximum length of maxlen. This is always SL240 in this release. This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_control( ) with a command type of TEKDX_DEV_IOCTL_GET_MODULE_ID. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_control( ) CAUTIONS None Page 9

13 tekdxfxslgetdriverid( ) NAME tekdxfxslgetdriverid( ) Get the driver identification string for the server. SYNOPSIS long tekdxfxslgetdriverid ( TEKDX_handle dx, char *buf, int maxlen ); DESCRIPTION This function retrieves the tekdx server and hardware driver version information for the tekdx stream specified by dx. The version information is copied into the string buffer at *buf with a maximum length of maxlen. The version string is in x.y.z format (e.g., ). This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_control( ) with a command type of TEKDX_DEV_IOCTL_GET_DRIVER_ID. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or ERROR if the operation is not successful. SEE ALSO tekdx_dev_control( ) CAUTIONS None Page 10

14 tekdxfxslgetmoduleinfo( ) NAME tekdxfxslgetmoduleinfo( ) Get module information. SYNOPSIS long tekdxfxslgetmoduleinfo ( TEKDX_handle dx, TEKDX_FXSL_INFO *infop ); DESCRIPTION This routine retrieves the module information structure from the module associated with the tekdx stream specified by dx. The module information structure is copied into the structure pointed at by *infop. The module information structure does not contain anything useful in this release. This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_control( ) with a command type of TEKDX_DEV_IOCTL_GET_MODULE_INFO. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_control() CAUTIONS None Page 11

15 Configuration Functions The tekdxfxsl client software provides functions to get and set the hardware configuration of the FXSL device. The tekdxfxsl software defines a common data structure that is used for hardware configuration of all supported FXSL devices. The parameter data structure is defined as follows: typedef struct { /* driver configuration parameters */ int use_flow_control; /* NZ to enable */ int convert_dsync; /* NZ to enable */ int halt_on_link_errors; /* NZ to enable */ int allow_qing_on_lerror; /* NZ to enable */ int usecrc; /* NZ to enable */ /* transfer parameters */ int usesync; /* NZ to enable */ int swapbytes; /* NZ to enable */ } TEKDX_FXSL_PARMS; Please refer to the FibreXtreme SL100/SL240 API Guide for detailed information on the above options. To support future versions of the tekdxfxsl software, the recommended approach for hardware configuration is to get the parameter state, modify the desired fields by name, and then set the parameter state. This allows the user software to automatically adapt to future releases of the tekdxfxsl software that may include additional parameter fields to support new FXSL devices. The tekdxfxsl software provides four functions to get and set the configuration parameter state: tekdxfxslrxgetparms. This function retrieves the current FXSL parameter state for the receive stream (from the external input to the RACEway). tekdxfxslrxsetparms. This function sets the current FXSL parameter state for the receive stream. tekdxfxsltxgetparms. This function retrieves the current FXSL parameter state for the transmit stream (from the RACEway to the external output). tekdxfxsltxsetparms. This function sets the current FXSL parameter state for the transmit stream. Each of these functions is described in more detail below. Page 12

16 tekdxfxslrxgetparms( ) NAME tekdxfxslrxgetparms( ) Get the RX parameter state for the FXSL device. SYNOPSIS long tekdxfxslrxgetparms ( TEKDX_handle dx TEKDX_FXSL_PARMS *parms ); DESCRIPTION This routine retrieves the current parameter state for the tekdx receive stream specified by dx. The parameter state is copied into the *parms data structure. This function is valid even if the FXSL device does not support a receive stream. This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_control( ) with a command type of TEKDX_DEV_IOCTL_RX_GET_PARMS. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_control( ), tekdxfxslrxsetparms( ) CAUTIONS None Page 13

17 tekdxfxslrxsetparms( ) NAME tekdxfxslrxsetparms( ) Set the RX parameter state for the FXSL device. SYNOPSIS long tekdxfxslrxsetparms ( TEKDX_handle dx TEKDX_FXSL_PARMS *parms ); DESCRIPTION This routine sets the current parameter state for the tekdx receive stream specified by dx to the state specified by the *parms data structure. The parameter state is updated and the new parameter state is copied back into *parms. This function is valid even if the FXSL device does not support a receive stream; the configuration is just ignored. This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_control( ) with a command type of TEKDX_DEV_IOCTL_RX_SET_PARMS. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_control( ), tekdxfxslrxgetparms( ) CAUTIONS This routine should not be invoked if data transfers are currently in progress. Page 14

18 tekdxfxsltxgetparms( ) NAME tekdxfxsltxgetparms( ) Get the TX parameter state for the FXSL device. SYNOPSIS long tekdxfxsltxgetparms ( TEKDX_handle dx TEKDX_FXSL_PARMS *parms ); DESCRIPTION This routine retrieves the current parameter state for the tekdx transmit stream specified by dx. The parameter state is copied into the *parms data structure. This function is valid even if the FXSL device does not support a transmit stream. This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_control( ) with a command type of TEKDX_DEV_IOCTL_TX_GET_PARMS. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_control( ), tekdxfxsltxsetparms( ) CAUTIONS None Page 15

19 tekdxfxsltxsetparms( ) NAME tekdxfxsltxsetparms( ) Set the TX parameter state for the FXSL device. SYNOPSIS long tekdxfxsltxsetparms ( TEKDX_handle dx TEKDX_FXSL_PARMS *parms ); DESCRIPTION This routine sets the current parameter state for the tekdx transmit stream specified by dx to the state specified by the *parms data structure. The parameter state is updated and the new parameter state is copied back into *parms. This function is valid even if the FXSL device does not support a transmit stream; the configuration is just ignored. This function blocks the calling task until the operation is completed. It is not appropriate for inner-loop code. This function is equivalent to calling tekdx_dev_control( ) with a command type of TEKDX_DEV_IOCTL_TX_SET_PARMS. INCLUDE FILES tekdx.h, tekdxfxsl.h RETURNS TEKDX_SUCCESS, or TEKDX_ERROR if the operation is not successful. SEE ALSO tekdx_dev_control( ), tekdxfxsltxgetparms( ) CAUTIONS This routine should not be invoked if data transfers are currently in progress. Page 16

20 Device Configurations The tekdxfxsl software provides an abstract interface to a family of PMC modules that generically provide FibreXtreme functionality. This section of the manual defines the capabilities and specific limitations of each supported PMC module. This material is intended as an overview only; please consult the PMC s documentation for current hardware capabilities and features. Systran FibreXtreme SL Gbps VITA 17.1 FibreXtreme Interface Supports receive stream, raw mode. Supports transmit stream, raw mode. Supports byte-swapping. Systran FibreXtreme SL Gbps VITA 17.1 FibreXtreme Interface Supports receive stream, raw mode. Supports transmit stream, raw mode. Supports byte-swapping. Page 17