software and api guide for the multi-channel … and api guide for the multi-channel sl100/sl240 ......

Software and API Guide

for the Multi-Channel SL100/SL240

Document No. F-T-ML-S2APINSL-A-0-A2

FOREWORD

The information in this document has been carefully checked and is believed to be accurate; however, no responsibility is assumed for inaccuracies. Curtiss-Wright Controls, Inc. reserves the right to make changes without notice.

Curtiss-Wright Controls, Inc. makes no warranty of any kind with regard to this printed material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

© Copyright 2007 Curtiss-Wright Controls, Inc., All rights reserved. is a registered trademark of Curtiss-Wright Controls, Inc.

Visual C++ is a trademark and a product of Microsoft Corporation. Windows® is a trademark and a product of Microsoft Corporation.

VxWorks® is a registered trademark of Wind River Systems. UNIX® is a registered trademark of the Digital Equipment Corporation. Solaris® is a registered trademark of Sun Microsystems, Inc.

Linux® is a registered trademark of Linus Torvalds.

Any reference made within this document to equipment from other vendors does not constitute an endorsement of their product(s). Published: October 24, 2007

Curtiss-Wright Controls Embedded Computing Data Communications 4126 Linden Avenue

Dayton, OH 45432-3018 USA Tel: (800) 252-5601(U.S. only)

Tel: (937) 252-5601

Copyright 2007 i NSL Software and API Guide

TABLE OF CONTENTS

1. INTRODUCTION...................................................................................................................................... 1-1 1.1 How to Use This Manual.......................................................................................................... 1-1

1.1.1 Purpose .................................................................................................................. 1-1 1.1.2 Scope ..................................................................................................................... 1-1 1.1.3 Style Conventions.................................................................................................. 1-1

1.2 Related Information.................................................................................................................. 1-1 1.3 Quality Assurance .................................................................................................................... 1-2 1.4 Technical Support..................................................................................................................... 1-3 1.5 Ordering Process ...................................................................................................................... 1-3

2. SOFTWARE OVERVIEW ........................................................................................................................ 2-1 2.1 Overview .................................................................................................................................. 2-1 2.2 Device Driver ........................................................................................................................... 2-1 2.3 API Library .............................................................................................................................. 2-1 2.4 Utility Applications .................................................................................................................. 2-1 2.5 Software Directory Structure.................................................................................................... 2-1

3. API DESCRIPTION .................................................................................................................................. 3-1 3.1 Overview .................................................................................................................................. 3-1 3.2 Structures.................................................................................................................................. 3-2

3.2.1 nslDeviceInfo......................................................................................................... 3-2 3.2.2 nslSeq .................................................................................................................... 3-3

3.3 API Functions........................................................................................................................... 3-4 3.3.1 nslOpen.................................................................................................................. 3-5 3.3.2 nslClose ................................................................................................................. 3-6 3.3.3 nslRecv, nslSend.................................................................................................... 3-7 3.3.4 nslGetDeviceInfo................................................................................................... 3-9 3.3.5 nslGetState, nslSetState ....................................................................................... 3-10 3.3.6 nslGetErrStr ......................................................................................................... 3-12

3.4 Return Codes .......................................................................................................................... 3-13 4. UTILITY APPLICATIONS....................................................................................................................... 4-1

4.1 Application Overview .............................................................................................................. 4-1 4.2 Application Descriptions .......................................................................................................... 4-1

4.2.1 nslmon – Device Monitor and Configuration Tool ................................................ 4-1 4.2.2 nsltp – Network Throughput Graphing Tool.......................................................... 4-1 4.2.3 nslvex – Network Exerciser ................................................................................... 4-1 4.2.4 ngtmem – Memory/Register Access Utility........................................................... 4-2

TABLE OF CONTENTS

Copyright 2007 ii NSL Software and API Guide

APPENDICES

APPENDIX A PRIMITIVES....................................................................................................................... A-1 APPENDIX B INSTALLATION................................................................................................................. B-1

Copyright 2007 1-1 NSL Software and API Guide

1. INTRODUCTION 1.1 How to Use This Manual 1.1.1 Purpose

This manual describes how to use the NSL software. The NSL Application Program Interface (API), utility applications, and software installation procedures are discussed.

1.1.2 Scope This manual is intended for system and software developers who want to call the API Library routines in applications programming.

Operating-system-specific installation information is included in appendix B. 1.1.3 Style Conventions

• Called functions are italicized. For example, OpenConnect(). • Data types are italicized. For example, int. • Function parameters in textual references are bolded. For example, Action. • Path names are italicized. For example, utility/sw/cfg. • File names are bolded. For example, config.c. • Path file names are italicized and bolded. For example, utility/sw/cfg/config.c. • Hexadecimal values are written with a “0x” prefix. For example, 0x7e. • Code and monitor screen displays of input and output are boxed and indented on

a separate line. Text that represents user input is bolded. Text that the computer displays on the screen is not bolded. For example:

ls file1 file2 file3

• Large samples of code are Courier font, at least one size less than context, and are usually on a separate page or in an appendix.

1.2 Related Information • FibreXtreme Hardware Reference Manual for the SL100/SL240 Multi-Channel

PCIe Cards • Fibre Channel Association Product Information Bulletin Revision, December 9,

1994. • Front Panel Data Port Specifications, ANSI/VITA 17-1998, Revision 1.0;

February 11, 1999. Produced by the VITA Standards Organization. • American National Standard for XMC PCI Express Protocol Layer Standard,

ANSI/VITA 42.3-2006, http://www.vita.com • American National Standard for Serial Front-Panel Data Port, ANSI/VITA 17.1-

2003, http://www.vita.com • Curtiss-Wright Controls, Inc. www.cwcembedded.com

http://www.vita.com/

http://www.vita.com/

http://www.cwcembedded.com/

INTRODUCTION


1.3 Quality Assurance Curtiss-Wright Controls, policy is to provide our customers with the highest quality products and services. In addition to the physical product, the company provides documentation, sales and marketing support, hardware and software technical support, and timely product delivery. Our quality commitment begins with product concept, and continues after receipt of the purchased product.

Curtiss-Wright Controls’ Quality System conforms to the ISO 9001 international standard for quality systems. ISO 9001 is the model for quality assurance in design, development, production, installation, and servicing. The ISO 9001 standard addresses all 20 clauses of the ISO quality system, and is the most comprehensive of the conformance standards.

Our Quality System addresses the following basic objectives: • Achieve, maintain, and continually improve the quality of our products through

established design, test, and production procedures. • Improve the quality of our operations to meet the needs of our customers,

suppliers, and other stakeholders. • Provide our employees with the tools and overall work environment to fulfill,

maintain, and improve product and service quality. • Ensure our customer and other stakeholders that only the highest quality product

or service will be delivered.

The British Standards Institution (BSI), the world’s largest and most respected standardization authority, assessed Curtiss-Wright Controls’ Quality System. BSI’s Quality Assurance division certified we meet or exceed all applicable international standards, and issued Certificate of Registration, number FM 31468, on May 16, 1995. The scope of Curtiss-Wright Controls’ registration is: “Design, manufacture and service of high technology hardware and software computer communications products.” The registration is maintained under BSI QA’s bi-annual quality audit program.

Customer feedback is integral to our quality and reliability program. We encourage customers to contact us with questions, suggestions, or comments regarding any of our products or services. We guarantee professional and quick responses to your questions, comments, or problems.

INTRODUCTION


1.4 Technical Support

Technical documentation is provided with all of our products. This documentation describes the technology, its performance characteristics, and includes some typical applications. It also includes comprehensive support information, designed to answer any technical questions that might arise concerning the use of this product. We also publish and distribute technical briefs and application notes that cover a wide assortment of topics. Although we try to tailor the applications to real scenarios, not all possible circumstances are covered.

Although we have attempted to make this document comprehensive, you may have specific problems or issues this document does not satisfactorily cover. Our goal is to offer a combination of products and services that provide complete, easy-to-use solutions for your application.

If you have any technical or non-technical questions or comments, contact us. Hours of operation are from 8:00 a.m. to 5:00 p.m. Eastern Standard/Daylight Time.

• Phone: (937) 252-5601 or (800) 252-5601 • E-mail: [email protected] • Fax: (937) 252-1465 • World Wide Web address: www.cwcembedded.com

1.5 Ordering Process

To learn more about Curtiss-Wright Controls, Inc. products or to place an order, please use the following contact information. Hours of operation are from 8:00 a.m. to 5:00 p.m. Eastern Standard/Daylight Time.

• Phone: (937) 252-5601 or (800) 252-5601 • E-mail: [email protected] • World Wide Web address: www.cwcembedded.com



INTRODUCTION


This page intentionally left blank


2. NSL SOFTWARE OVERVIEW 2.1 Overview

This next generation of SL100/SL240 software referred to as NSL is designed to facilitate application software development. It is an easy-to-use interface that abstracts the complex details of device drivers, DMA transactions etc., and allows you to write effective software with minimal complication. The software consists of a device driver, API library, and a set of utility applications. See Appendix B for the software installation procedure for your operating system.

2.2 Device Driver The device driver performs operations on the SL100/SL240 hardware in response to requests from the API library and the hardware itself. There is a separate device driver for each platform supported by the NSL software.

2.3 API Library The API library is the interface applications use to communicate with the device driver. It is a simple platform-independent interface covering all the features supported by the hardware. The full set of API functions is described in Chapter 3.

2.4 Utility Applications A set of utility applications is distributed with the NSL software. These applications serve both as useful utilities and as examples of how to write software using NSL.

2.5 Software Directory Structure

nsl |-- api |-- apps | |-- nslutils |-- dcficore |-- inc |-- osname* | |-- bin | |-- driver |-- lib

• api directory contains API source code • nslutils directory contains source code for NSL

utilities. • dcficore directory contains core driver files. • inc directory contains API header files. • osname* directory is the operating-system-

specific directory. • bin directory contains binaries for the utilities. • driver directory contains the driver(s), and

related files. • lib directory contains the compiled API library.

* Replace the name “osname” with your specific operating system.

SOFTWARE OVERVIEW




3. API DESCRIPTION 3.1 Overview

This chapter describes the NSL API in detail. First, the structures defined by the API are described in section 3.2. Then the API functions and their arguments are described in detail in section 3.3. Lastly, possible return codes of the API functions are described in section 3.4. Note that base data types (for example, int32) are used throughout the API. This ensures compatibility across platforms and compilers. See Appendix A for a detailed description of these base types. In addition to the NSL API, a legacy compatibility layer is provided. See inc/fxslapi.h and the FibreXtreme SL100/SL240 API Guide (F-T-ML-S2API###-A-0-A8) for reference. To make use of the compatibility layer, link your program to both the compatibility library and the standard nslapi library.

API DESCRIPTION


3.2 Structures

Structures are used to retrieve the status of the driver to store sequence information for receive operations. These structures are described here.

3.2.1 nslDeviceInfo

Note: The structures defined below should not be relied on for relative placement of structure members.

The type nslDeviceInfo returns information about the device.

typedef struct _nslDeviceInfo { char driverRevisionStr[128]; char boardLocationStr[128]; uint32 unitNum; uint32 linkSpeed; uint32 popMemSize; uint32 numLinks; uint32 revisionID; uint32 serialNumL; uint32 serialNumH; } nslDeviceInfo;

MEMBERS: driverRevisionStr: ..........................NULL-terminated string giving revision information of

the driver currently running.

boardLocationStr: ..........................NULL-terminated string describing the physical location of the device.

unitNum: .........................................Unit number of the device.

linkSpeed: ........................................Link speed in Megahertz (e.g., 2500 Mhz).

popMemSize:...................................Memory size in bytes that is populated on the device. This memory is used as a receive FIFO and is not available for general use.

numLinks: .......................................Number of supported network interfaces on the device.

revisionID:.......................................The firmware revision ID.

serialNumL: ....................................Lower 32-bits of board serial number.

serialNumH: ....................................Upper 32-bits of board serial number.

API DESCRIPTION


3.2.2 nslSeq

The type nslSeq returns sequence information about a receive operation. This can be used to order data obtained using nslRecv() when using multiple threads.

typedef struct _nslSeq { uint64 seqNum; uint64 startByteNum; } nslSeq;

MEMBERS: seqNum:...........................................Sequence number for the receive operation. If data B

has a higher associated sequence number than data A, then data B was received after data A.

startByteNum: ................................The count of bytes received before the first byte of the associated receive operation.

API DESCRIPTION


3.3 API Functions

The NSL API contains a variety of functions. They allow you to send and receive data, configure the driver, and get driver information in a variety of ways. The function prototypes are found in the file nslapi.h (located in the inc directory) and detailed in Table 3-1 below. All functions return “NSL_SUCCESS” upon successful completion, unless otherwise specified. For a complete description of possible return codes, see Section 3.4.

Table 3-1 API Functions

Function Description Page nslOpen Initializes a handle to a specific adapter that is then

passed to all other API calls that will operate on that device.

3-5

nslClose Closes a handle to a device. 3-6 nslSend Send data to the NSL network. 3-7 nslRecv Receive data from NSL. 3-7 nslGetDeviceInfo Retrieve information about the device. 3-9 nslGetState Get the value of a specified configuration parameter. 3-10 nslSetState Set the value of a specified configuration parameter. 3-10 nslGetErrStr Returns a string describing a specific error code. 3-12

In addition to these functions, the API provides a global variable nslapiRevisionStr that points to a NULL-terminated string containing API revision information.

API DESCRIPTION


3.3.1 nslOpen

FUNCTION PROTOTYPE: uint32 nslOpen (uint32 unitNum, nslHandle *pHandle);

DESCRIPTION:

Initializes a handle to a specific NSL device. Pass this handle to all other API calls to operate on the device.

INPUT: unitNum: .........................................Unit number of the device to open. Valid unit

numbers range from 0 to 15. Use nslmon with the '-a' option to see the available unit numbers.

OUTPUT: pHandle: ..........................................Pointer to a nslHandle variable. After successful

completion *pHandle will contain a handle to a device.

API DESCRIPTION


3.3.2 nslClose

FUNCTION PROTOTYPE: uint32 nslClose (nslHandle *pHandle);

DESCRIPTION:

Closes a handle to a device.

INPUT: pHandle: ..........................................Pointer to a device handle.

WARNING: The handle becomes invalid once closed. If the handle is used after it has been closed, the results are undefined.

API DESCRIPTION


3.3.3 nslRecv, nslSend FUNCTION PROTOTYPE:

uint32 nslRecv(nslHandle *pHandle, uint32 nslSend(nslHandle *pHandle void *pDataBuffer, void *pDataBuffer, uint32 bytesToTransfer, uint32 bytesToTransfer, uint32 flagsIn, uint32 flagsIn, uint32 timeout, uint32 timeout, uint32 *pBytesTransferred); uint32 *pBytesTransferred, uint32 *pFlagsOut, uint32 *pFlagsOut); nslSeq *pSeq);

DESCRIPTION: The nslRecv() and nslSend() functions performs receive and send DMA transfers to and from the NSL device. The nslRecv() function reads data from the NSL device into the data buffer. The nslSend() function writes data from the data buffer to the NSL link. The nslRecv() and nslSend() functions perform 32-bit sized transfers.

INPUT: pHandle: ..........................................Pointer to a device handle. pDataBuffer: ...................................Pointer to a user buffer. bytesToTransfer: ............................Number of bytes to transfer. This value is rounded

down to the nearest multiple of 4. flagsIn: .............................................Bit vector containing the input flags for the transfer.

See Table 3-2 for the bit definitions. timeout:............................................Transfer timeout value in milliseconds. Resolution is to

the nearest 10 ms. Note that this timeout value applies to each 256K byte chunk in the data buffer. For 512K bytes the maximum total timeout that can be experienced is twice this value for example.

OUTPUT: *pBytesTransferred: ......................Number of bytes transferred. This value is always a

multiple of 4.

*pFlagsOut:.....................................Transfer completion flags. See Table 3-2 for the bit definitions.

*pSeq: ..............................................Structure containing sequence number information for the transfer. This can be used to order transfers when using multiple threads. Pass NULL if you do not want this information.

RETURN VALUES: NSL_SUCCESS: ............................. Indicates a successful transfer.

NSL_LINK_ERROR: .................... Indicates that the transfer was stopped because a link error occurred. To disable stopping on link error set the NSL_STOP_ON_LNK_ERR to ‘0’. See nslSetState().

NSL_TIMEOUT:............................ Indicates that the transfer was stopped because it exceeded the timeout time.

API DESCRIPTION


Table 3-2 Flag Bit Definition

Flag bit definition Input/Output(I|O)

Description

NSL_DMA_USE_SYNC IO Specifies the use of SYNC for the requested transaction. If the NSL_DMA_USE_SYNC bit is ‘1’ and the operation is a send, then the SYNC is sent at the end of the transmission; if it is ‘0,’ then no SYNC is transmitted. If the NSL_DMA_USE_SYNC bit is ‘1’ and the operation is a receive, then the reception is ended if a SYNC is received before the byte count is satisfied and the NSL_DMA_USE_SYNC bit is returned as ‘1’ in the flagsOut parameter.

NSL_DMA_USE_SYNCDV IO Specifies the use of SYNC with DVALID for the requested transaction. If the NSL_DMA_USE_SYNCDV bit is ‘1’ and the operation is a send, then the SYNC with DVALID is sent at the end of the transmission; if it is ‘0,’ then SYNC with DVALID is transmitted. If the NSL_DMA_USE_SYNCDV bit is ‘1’ and the operation is a receive, then the reception is ended if the SYNC with DVALID is received before the byte count is satisfied and the NSL_DMA_USE_SYNCDV bit is returned as ‘1’ in the flagsOut parameter.

NSL_DMA_BYTE_SWAP I Specifies byte-swapping of the data in conjunction with the NSL_EN_BYTE_SWAP state (See nslSetState()). Byte swapping occurs if either the NSL_DMA_BYTE_SWAP bit is ‘1’ and the NSL_EN_BYTE_SWAP state is ‘0,’ or the NSL_DMA_BYTE_ SWAP bit is ‘0’ while the NSL_EN_BYTE_SWAP parameter is ‘1.’ Otherwise, bytes are not swapped during the data transfer.

NSL_DMA_WORD_SWAP I Specifies 32-bit word-swapping of the data in conjunction with the NSL_EN_WORD_SWAP state (See nslSetState()). Word swapping occurs if either the NSL_DMA_WORD_SWAP bit is ‘1’ and the NSL_EN_WORD_SWAP state is ‘0,’ or the NSL_ DMA WORD_SWAP bit is ‘0’ while the NSL_EN_WORD _SWAP parameter is ‘1.’ Otherwise, words are not swapped during the data transfer.

NSL_DMA_TIMEOUT O This bit is set in the flagsOut parameter when the send or receive operation ends because of a timeout. This is in addition to the return value of nslRecv() and nslSend() indicating that a timeout occurred by returning NSL_TIMEOUT.

NSL_DMA_LNK_ERR O This bit is set to ‘1’ in the flagsOut parameter when a link error has occurred during the send or receive operation. This is in addition to the return value of nslRecv() and nslSend() indicating that a link error occurred by returning NSL_LINK_ERROR when the NSL_STOP_ON_LNK_ERR state is set to ‘1’. When NSL_ STOP_ON_LNK_ERR is ‘0’, this is the only indication that a link error occurred.

NSL_DMA_PHYS_ADDR I Specifies that pDataBuffer is a physical PCI addresses rather than a virtual memory address. This facilitates direct transfer from one PCI device to another. Use caution when using physical addresses because there is no verification that the address is correct. This may lead to system lock or memory corruption in the case of an incorrect physical address.

API DESCRIPTION


3.3.4 nslGetDeviceInfo FUNCTION PROTOTYPE:

uint32 nslGetDeviceInfo (nslHandle *pHandle, nslDeviceInfo *pDeviceInfo);

DESCRIPTION: Retrieves information about a device.

INPUT: pHandle: ..........................................Pointer to a device handle.

OUTPUT: pDeviceInfo: ....................................Pointer to a device info structure. The structure is

updated with the status of the device.

API DESCRIPTION


3.3.5 nslGetState, nslSetState

FUNCTION PROTOTYPE: uint32 nslGetState(nslHandle *pHandle, uint32 nslSetState(nslHandle *pHandle,

uint32 stateID); uint32 stateID, uint32 val);

DESCRIPTION: The nslGetState() function returns the current state of a driver resource identified by the value of stateID. The nslSetState() function sets the current state of a driver resource identified by the value of stateID. See Table 3-3 State ID to determine which driver resources are settable.

INPUT: pHandle: .............................................. Pointer to a device handle. stateID: ................................................ State identifier. Can be one of the following values.

Table 3-3 State ID

stateID Settable Description NSL_RX_TRFC_CNTR No Receive traffic counter. Counts the total number of

32-bit words received from the link. NSL_TX_TRFC_CNTR No Transmit traffic counter. Counts the total number of

32-bit words transmitted over the link. NSL_EN_EWRAP Yes Set to '1' to enable electronic wrap and bypass the

link. Set to '0' to disable. NSL_NET_TIMER_VAL No Timer that is incremented on every network transmit

clock period. For 2.5 Gbps configuration, the network transmit clock period is 8 ns. See the hardware manual for additional information.

NSL_EN_TRANSMIT Yes Set to '1' to enable transmit to the link. Set to '0' to disable.

NSL_EN_RECEIVE Yes Set to '1' to enable reception from the link. Set to '0' to disable.

NSL_EN_RETRANSMIT Yes Set to '1' to enable retransmit of received data. Set to '0' to disable.

NSL_EN_CRC Yes Set to '1' to enable CRC check/send. Set to ‘0’ to disable.

NSL_EN_FLOW_CTRL Yes Set to '1' to enable flow control. Set to ‘0’ to disable. NSL_EN_LASER Yes Set to '1' to enable laser. Set to '0' to disable. NSL_LINK_UP No Link up status. ‘1’ if link up, ‘0’ if down NSL_SIGNAL_DET No Signal detect state for laser. ‘1’ if signal detected, ‘0’ if

no signal detected. NSL_EN_D64 Yes Set to '1' to enable 64-bit PCI data transfers by the

DMA engine. Set to '0' to allow only 32-bit PCI data transfers by the DMA engine.

NSL_EN_BYTE_SWAP Yes Set to '1' to enable byte swapping of data. Set to '0' to disable.

NSL_EN_WORD_SWAP Yes Set to '1' to enable swapping of 32-bit words for data

API DESCRIPTION


stateID Settable Description transfer. Set to '0' to disable.

NSL_FPDP_IN No FPDP input signals. The following bit definitions exist: NSL_FPDP_PIO1, NSL_FPDP_PIO2, NSL_FPDP_DIR, and NSL_FPDP_NRDY.

NSL_FPDP_OUT Yes FPDP output signals. See FPDP_IN for bit definitions. NSL_LNK_ERR_CNTR No Number of link errors. NSL_LNK_DOWN_CNTR No Number of link down events. NSL_DEC_ERR_CNTR No Number of decoder errors. NSL_INTR_CNTR No Counts the number of hardware interrupts generated

by the device. NSL_TX_FRAME Yes Maximum TX frame size in 32-bit words. [0,4095]

The maximum specified in the serial FPDP standard is 512

NSL_TX_GAP Yes Minimum inter-frame gap in 32-bit words. [0,65535] NSL_MAX_TIMEOUT Yes The maximum allowed timeout value for nslSend()

and nslRecv() transactions in milliseconds. NSL_STOP_ON_LNK_ERR Yes Set to ‘1’ to enable stopping DMA transfers when a

link error occurs. Set to ‘0’ to disable. NSL_CLR_SEQ Yes Setting this state to any value causes the nslSeq

information returned by nslRecv() to be set to 0.

val:....................................................The nslSetState() function sets the state of the driver resource to this value.

API DESCRIPTION


3.3.6 nslGetErrStr

FUNCTION PROTOTYPE char * nslGetErrStr(uint32 retcode);

DESCRIPTION

Returns a NULL-terminated string describing the return code of a NSL API call. Returns the string “Unknown Error,” if the return code is not valid.

INPUT: retcode: ............................................Return code of the error to describe.

API DESCRIPTION


3.4 Return Codes

Each function in the NSL API returns NSL_SUCCESS or an error code unless otherwise specified. The possible return codes are listed in Table 3-4.

Table 3-4 Return Codes

Name Description NSL_SUCCESS Successful completion. NSL_SYSTEM_ERROR System error. NSL_BAD_PARAMETER An invalid parameter was received by an

API call. An invalid parameter can be a value outside the specified range or a NULL pointer.

NSL_DRIVER_ERROR The driver encountered an internal error. NSL_TIMEOUT The time-out expired before the call

completed. NSL_CALL_UNSUPPORTED The requested call was not supported. NSL_INSUFFICIENT_RESOURCES Resources are not available to complete

a call. NSL_LINK_ERROR Link error occurred during DMA transfer. NSL_HARDWARE_ERROR Unexpected hardware error occurred.


4. UTILITY APPLICATIONS 4.1 Application Overview

The NSL software comes with a variety of utility applications. These utilities are provided to assist in verifying the card’s functionality, to assist in application development, and to provide examples using the NSL API.

4.2 Application Descriptions Application options are documented within each application’s help menus. Running an application without options will display a condensed help menu. Use option ‘-h’ for descriptive help with options. Use option ‘-h 1’ for extensive application usage and options information. For example:

nslmon -h

nsltp -h 1

4.2.1 nslmon – Device Monitor and Configuration Tool Use the nslmon tool to monitor device status or modify driver and device configuration settings. For example:

• Determine the device status and configuration • Display performance statistics

While nslmon is a valuable stand-alone tool, it is also a powerful tool for use in shell scripting.

4.2.2 nsltp – Network Throughput Graphing Tool The nsltp tool is used to test device performance in a computer system. Though NSL devices are capable of transmitting data at their documented maximum data rate, many factors can reduce the total system performance. Some of these factors are bus speed, CPU frequency, and memory speed. For example:

• Graph network throughput versus data packet size • Determine optimal packet sizes for use in new applications • Generate network loads during testing

The nsltp tool has options for transferring data with multiple simultaneous threads of execution. It is the perfect tool for diagnosing and optimizing your system performance.

4.2.3 nslvex – Network Exerciser The nslvex application is a generator and verifier of network traffic. This application exercises nodes on the network by using a sending node and a receiving node. This is useful for:

• Evaluating network stability • Verify network functionality (including data verification) • Perform a quick network test

UTILITY APPLICATIONS


4.2.4 ngtmem – Memory/Register Access Utility The ngtmem utility provides access to device registers. For example:

• Display and modify device registers • Monitor changes in device registers

Like nslmon, ngtmem is also a powerful tool for use in shell scripting.

A. A – PRIMITIVES

APPENDIX A

PRIMITIVES

TABLE OF CONTENTS A.1 Basic Data Types ................................................................................................................................... A-1

PRIMITIVES

Copyright 2007 A-1 NSL Software and API Guide

A.1 Basic Data Types The NSL API defines a set of base data types that are used throughout the API. This ensures compatibility across platforms and compilers. These data types are described below.

int64 ....................................The type int64 is a signed 64-bit integer.

uint64 ..................................The type uint64 is an unsigned 64-bit integer.





int8 ......................................The type int8 is a signed 8-bit integer.

uint8 ....................................The type uint8 is an unsigned 8-bit integer.

nslHandle............................The type nslHandle is an abstraction of the file descriptor in UNIX, the HANDLE in Windows, and other similar descriptors used by other operating systems. The NSL API uses a nslHandle to determine which device the request should be executed on. Consult the example applications for more information on using the type nslHandle.

B. B – INSTALLATION

APPENDIX B

INSTALLATION

TABLE OF CONTENTS A.1 Basic Data Types ................................................................................................................................... A-1 B.1 Overview.................................................................................................................................................B-1 B.2 Install the Hardware ................................................................................................................................B-1 B.3 Windows Software Installation ...............................................................................................................B-2

B.3.1 Install the Device Driver.......................................................................................................B-2 B.3.2 Install the API Library and Utility Applications...................................................................B-5 B.3.3 Rebuilding Applications .......................................................................................................B-5 B.3.4 Linking with the API library.................................................................................................B-5

B.4 UNIX-like OS Software Installation .......................................................................................................B-6 B.4.1 Install the Software onto the Host Computer (UNIX) .........................................................B-6 B.4.2 Loading/Unloading NSL Device Driver ...............................................................................B-7 B.4.3 Rebuilding Applications .......................................................................................................B-7

INSTALLATION

Copyright 2007 B-1 NSL Software and API Guide

B.1 Overview To install the NSL software, complete the following steps:

• Install the hardware. • Install the software. See the installation section for your operating system.

NOTE: This NSL device driver can support between one and sixteen NSL channels total on each host computer.

B.2 Install the Hardware Install the SL100/SL240 hardware before installing the NSL software. See the FibreXtreme Hardware Reference Manual for SL100/SL240 Multi-Channel PCIe Cards for details on installing hardware in the host system.

INSTALLATION


B.3 Windows Software Installation This section describes how to install the software on Windows operating systems. Supported Windows platforms include:

• Windows 2000 • Windows XP • Windows Server 2003 • Windows Vista

B.3.1 Install the Device Driver On the first boot after the hardware is installed, Windows will detect the SL100/SL240 card as shown in Figure B-1 and Figure B-2 below.

NOTE: To upgrade the Windows device driver from an existing installation, execute the win2kUpdateDriver.exe program provided on the CD-ROM and proceed to section B.3.2.

Figure B-1 Found New Hardware

Figure B-2 Found New Hardware Wizard

Click the Next button shown in Figure B-2 to begin the device driver installation.

INSTALLATION


Figure B-3 Search for Driver

As shown in Figure B-3 click the Next button to have Windows search for the driver.

Figure B-4 Search the CD-ROM

Make sure the NSL Software CD is in the drive, and as shown in Figure B-4 the ‘CD-ROM drives’ box is checked, and then click the Next button. Windows will then find the INF file for the driver on the CD-ROM. Click the Next button to install the driver.

INSTALLATION


NOTE: At this time the NSL driver has not received a digital signature. A dialog may appear warning you of this fact. Click the Yes button to install the driver anyway.

NOTE: If you have set your Local Security Settings to prohibit installing unsigned drivers, you will not be able to install the driver without changing these security settings.

Figure B-5 Driver Installation Completed

After Windows has finished installing the driver click the Finish button shown in Figure B-5. The driver should now be running, and will restart automatically whenever the computer is rebooted.

INSTALLATION


B.3.2 Install the API Library and Utility Applications The NSL API and utility applications are distributed as a self-extracting zip file. The file is located in the software directory on the CD-ROM. Install the software by simply running the executable and choosing a location to extract the files. The default location is c:\nsl.

B.3.3 Rebuilding Applications Application executable files are supplied with the software and are located in the winxp/bin directory. The applications were built with Microsoft Visual C++ version 6.0. If it is necessary to modify the source files, you can rebuild the applications using the provided makefile and the nmake Visual C++ utility. For example:

cd apps\nxutils nmake –f mnsl.windows.mak

You may need to execute the vcvars32.bat file distributed with Visual C++ to set the appropriate environment variables in order to execute nmake. See the Visual C++ documentation for more information.

B.3.4 Linking with the API library The NSL API is distributed in a static library format under Windows. User applications that wish to use the NSL API calls must link in the library. The following instructions will show how to link a user application with the NSL API using Microsoft Visual C++ 6.0 project files.

• Make sure that the NSL API header files can be found. Add the NSL inc directory to the 'Additional include directories:' list. The ‘Additional include directories:’ list is located in Project Settings under the Visual C++ tab when the Category list box is set to ‘Preprocessor.’ For example, add C:\nsl\inc to this list.

• Add the static library (nslapi.lib) located in the winxp\lib directory to the project’s file list.

Once these steps are completed, the application can be compiled and linked in the usual fashion.

INSTALLATION


B.4 UNIX-like OS Software Installation This section describes how to install the software on UNIX-like operating systems. Supported platforms include:

• Linux • Solaris

Contact Curtiss-Wright Controls Technical Support for specific versions supported.

B.4.1 Install the Software onto the Host Computer (UNIX) The following sections describe how to install the software. Software is distributed on a CD-ROM as a UNIX .tar.gz file. The instructions below assume that the login session will be using a terminal window.

To install the NSL software on your system: • Place the CD-ROM in the drive. • Login to the system as root (superuser). • Mount the CD-ROM if it is not already mounted. For example:

mount /mnt/cdrom

• Change to the desired destination directory. Here we use /usr/local.

cd /usr/local/

• Extract the distribution tar.gz file. For example:

gzip –dc /mnt/cdrom/software/nsl-X.tar.gz | tar xf -

Replace 'X' in the above file name to match the date in the file name supplied on the CD-ROM.

These procedures will place the contents of the tar file into the /usr/local/nsl directory.

If you are installing the software for Linux, we will now build the software. The software is pre-built for other operating systems.

cd nsl/ make –f makefile.linux

INSTALLATION


B.4.2 Loading/Unloading NSL Device Driver You must properly load the NSL device driver before it can be accessed.

First, change to the nsl driver directory for your OS by typing:

cd /usr/local/nsl/osname/driver

Next, execute the driver load script by typing:

./dload You can unload the driver by executing the unload script:

./dunload

B.4.3 Rebuilding Applications Application executable files are supplied with the software and are located in the osname/bin directory. If it is necessary to modify the source files you can rebuild the applications using the provided makefile for your operating system. For example:

cd apps/nxutils make -f mnsl.osname.mak

Where osname is the name of the operating system.

INSTALLATION



INDEX

Copyright 2007 INDEX 1 NSL Software and API Guide

A

API ......1-1, 2-1, 3-1, 3-4, 3-5, 3-12, 3-13, 4-1, A-1, B-5

B

binaries .......................................................................2-1

C

CD-ROM........................................... B-2, B-3, B-5, B-6

D

data types...................................................................A-1 device 2-1, 3-2, 3-3, 3-4, 3-5, 3-6, 3-7, 3-9, 3-10, 4-1, 4-

2 DMA.......................................................... 2-1, 3-7, 3-10 documentation ........................................................... B-5 driver ......................................... B-1, B-2, B-3, B-4, B-7

E

executable.......................................................... B-5, B-7

F

firmware revision .......................................................3-2 functions .....................................................................1-1

G

GT memory ......................................3-4, 3-7, 3-10, 3-11

I

ID 3-2, 3-10 ISO .............................................................................1-2

L

library .........................................................................2-1 Linux ......................................................................... B-6

M

monitor ................................................................1-1, 4-1

P

packet ......................................................................... 4-1 pHandle .......................................3-5, 3-6, 3-7, 3-9, 3-10 PIO ............................................................................. 3-7 Pointer .........................................3-5, 3-6, 3-7, 3-9, 3-10

R

restart......................................................................... B-4

S

scripting...............................................................4-1, 4-2 Solaris ....................................................................... B-6 stateID ...................................................................... 3-10

T

throughput .................................................................. 4-1 transfer ....................................................................... 3-7 transfers.............................................................3-7, 3-10

U

unitNum ..................................................................... 3-5 UNIX................................................................. A-1, B-6 utility ............................................ 1-1, 2-1, 4-1, 4-2, B-5

V

Visual C++ ................................................................ B-5

W

Windows ................................... A-1, B-2, B-3, B-4, B-5

Z

zip file ....................................................................... B-5

software and api guide for the multi-channel … and api guide for the multi-channel sl100/sl240 ......

Documents