Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI

8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI

1/110

Netaccess Series Release 7

QNX Neutrino Driver

Programmers Manual

Document Number 800-1015-001 AC

Printed May 2001


2/110

General Notices

B rooktrout Technology reserves the r ight t o ma ke changes or improvements to th e product described in th is ma nua lat an y time and w ithout notice. Every a ttempt ha s been made to insure that the informa tion contained in thisdocument is accurate and complete. However, Brooktrout Technology will not be responsible for any inaccuracies oromissions in this or any of its other technical publications.

The softwa re described in this ma nua l is furnished under a license and may not be used or copied only in a ccordancewith such license.

Brooktrout Technology will not be responsible for any loss of data or information resulting from the use of thisproduct. In no event will Brooktrout Technology be liable for any incidental, consequential, or indirect damages

(including but not limited to loss of business profits, business interruption, or loss of information) arising out of theuse or inability to use t his product. This includes an y claim by a ny other part y.

Copyright 2001 by Brooktrout Technology, Inc. All rights reserved. Neither this publication nor any part of thispublication ma y be copied, photocopied, reproduced, tra nsla ted or reduced to a ny electr onic medium or ma chinereada ble form w ithout prior w ritten permission from B rooktrout Technology.

Pr inted In U.S.A.

Trademarks

Inst an t IS DN Softw ar e, NS300, P RI-P CI, P RI-CP CI, P RI-ISA-24, PRI -ISA48, B RI-ISA8, an d SMI a re tra demarks ofB rooktrout Technology, In c.

QNX is a registered tra demark of QNX Softwa re Systems, Ltd.

Other t ra demarks used in th is publication a re property of th eir respective companies.

International Notice

Due to differing na tional regulat ions a nd a pproval r equirements, certain B rooktrout products ar e designed for useonly in specific countries, and ma y not fun ction properly in a countr y other t ha n t he countr y of designated use. As auser of these products, you ar e responsible for ensuring th at the products a re used only in the countries for w hichthey were intended. For information on specific products, contact Brooktrout Technology.

18 Keewaydin DriveSa lem, NH 03079603-898-1800www.brooktrout.com

Brooktrout Technical Support

For Brooktrout Technical Support, see Appendi x A.


3/110

Brooktrout Technology, Inc.

Software License Agreement

Proprietary Rights

The Software is subject to the protection of the copyright laws of the U.S. and foreign jurisdictions, which prohibituna uthorized copying a nd distr ibution of copyrighted w orks. The Softw ar e incorporates proprietary an d confidentialalgorithms a nd t echniques wh ich a re subject to legal protection as tra de secrets. B rooktrout is t he sole owner of all

proprietar y rights in the S oftw ar e, except for certa in portions w hich a re proprietary to third part y licensors ofBrooktrout. The User is granted only those rights expressly conferred by this License Agreement.

License

B rooktrout licenses the U ser to use t he Softw ar e subject to a nd in a ccordance with the following provisions. Thesoftw a re is distributed with netw ork interfa ce boards or boards with n etwork interface functionality tha t a reman ufactured a nd sold by Br ooktrout (Brooktrout Ha rdwa re), an d is licensed solely for use in connection w ith t heB rooktrout H ar dwa re. The Softw ar e, and modified versions thereof, ma y be opera ted only on the centra l processingunit of an y computer served by one or more items of B rooktrout H ar dwa re an d ma y, wh ere appropriat e in connectionwith such use, be down loaded onto memory locat ed on Br ooktrout Ha rdw ar e, and may be modified (if modification isotherwise permitted pursuant to the following provisions), reproduced and distributed only for purposes of such use.Any oth er use, modifica tion, reproduction or distr ibution is expressly prohibited.

Licensing provisions a pplica ble to part icular Softw ar e products a re a s follows:

1. AP I, Application a nd D river softw ar e and Downloada ble Firmwa re distributed in t he form of object code:

a. The User ma y incorporate th e Softwa re into his own work providing functiona l and va lue enha ncementsan d ma y duplicat e and distr ibute the resulting work as he chooses provided tha t t he resulting work isdesigned solely for use in connection w ith B rooktrout H a rdwa re and may be distributed only together wit hitems of Br ooktrout H ar dwa re solely for use in connection with such items.

b. The User may not modify the Software nor decompile, reverse engineer, disassemble, or otherwise reducethe Softw ar e to a huma n perceivable form.

c. When the User incorporates the Software into his product, Brooktrout's copyright notice must be includedin the new w ork.

2. AP I, Application or Dr iver softw a re distr ibuted in t he form of source code:

a. The User ma y modify the S oftwa re and must incorporate it int o his ow n w ork providing functiona l andvalue enha ncements. H e ma y duplicat e an d distribute t he resulting w ork in object code form only provided

tha t t he resulting work is designed solely for use in connection w ith B rooktrout H ar dwa re an d ma y bedistributed only together w ith items of Br ooktrout H ar dwa re solely for use in connection w ith such items.He ma y not distribute the Softw ar e in source form.

b.The Softwa re is confidential a nd proprieta ry to Br ooktrout a nd the U ser must protect it in a ma nner similarto the protection he a ffords his own confidential a nd proprieta ry informat ion.

c.When th e User incorporat es the Softw a re into his product, Brooktrout 's copyright notice must be included inthe new w ork.

The reproduction, distribution an d modificat ion r ights provided above applies to a ll Softwa re distributed byBr ooktrout un less a specific license agreement sta ting otherwise is a tta ched or part of a contract un der wh ich suchSoftware is being provided. In those cases, the specific license agreement will apply.

Distribution

Any distribut ion of the S oftw a re (including modified versions ther eof) wh ich is a uth orized hereby sha ll be ma de (a) inobject form only; (b) only to purchasers of units of Brooktrout Hardware, or of products including BrooktroutHa rdwa re, and (c) only pursuant to license agreements conta ining provisions substa ntia lly equivalent to thoseincluded herein wit h respect t o the Softw ar e distribution. Except as expressly permitted hereby, the user ma y notdistribute the Softwa re, or a ny copy by tran sfer, lease, loan or an y other means.

Termination

The User's license to use the Softw ar e may be terminat ed by Br ooktrout in t he event of any fa ilure to comply w ith t heabove restrictions or a ny other terms of th is License Agreement. In t he event of terminat ion of th e license, the Usermust destroy or return to B rooktrout a ll copies of th e Softwa re in his possession.


4/110

Limited Warranty

B rooktrout w ar ra nts for a period of 90 days following delivery tha t t he disk on w hich the Softwa re is recorded andwh ich is provided by B rooktrout is free from defects in mat erials and w orkmansh ip. B rooktrout does not w a rra nt t ha toperat ion of the Softw ar e will be uninterrupted or error-free, or t ha t it will sat isfy the U sers requirements.BROOKTROUT DISCLAIMS ALL OTHER WARRANTIES EXPRESS OR IMPLIED, INCLUDING ANY IMPLIEDWARRANTIES OF ME RCH ANTAB ILITY OR F ITNES S FOR A P ARTICU LAR P URP OSE.

Limitation of Liability

B rooktrouts entire liability an d th e Users exclusive remedy in connection w ith t he Softw ar e will be the replacementof any disk not meeting the a bove limited wa rra nty upon return of the disk to Brooktrout. In no event w ill Brooktroutbe lia ble for da ma ges, including any lost profits or other incidenta l or consequential da ma ges, arising out of or relatedto the S oftw ar e and its use, even is B rooktrout h as been a dvised of the possibility of such dam ages.


5/110

May 2001 v

Table of ContentsChapter 1Overview

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

QNX Driver Architecture and Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

General Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Management Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Driver Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Chapter 2Installation and Operation

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Preinstallation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Installation and Setup of the QNX Driver for Neutrino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Starting the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Uninstalling the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Running the Driver Test Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Tunable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

Chapter 3Driver Services

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

IOCTL_NAI_RESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

IOCTL_NAI_SEND_SRECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

IOCTL_NAI_SET_VTTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

IOCTL_NAI_CLEAR_VTTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

IOCTL_NAI_VTTY_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

IOCTL_NAI_VTTY_WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

IOCTL_NAI_CTL_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

IOCTL_NAI_CTL_WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10

IOCTL_NAI_READ_CRASH_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

IOCTL_NAI_DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12

IOCTL_NAI_GET_ADAP_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13

IOCTL_NAI_GET_STRM_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14

IOCTL_NAI_SET_DCHAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15

IOCTL_NAI_RUN_TEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16

IOCTL_NAI_TX_HALT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17

IOCTL_NAI_TX_RESUME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18

IOCTL_NAI_RX_HALT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19


6/110

vi Brooktrout Driver Programmers Manual

Table of Contents

IOCTL_NAI_RX_RESUME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20

IOCTL_NAI_SET_LOW_WATER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21

IOCTL_NAI_SET_MGMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22

IOCTL_NAI_SET_PULSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23

IOCTL_NAI_HS_GET_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24

IOCTL_NAI_HS_STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25

IOCTL_NAI_HS_GET_DEVICE_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26

IOCTL_NAI_HS_QUIESCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27

IOCTL_NAI_HS_USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28

IOCTL_NAI_HS_AUTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29

IOCTL_NAI_HS_DISABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30

IOCTL_NAI_HS_INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31

IOCTL_NAI_HS_REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32

Chapter 4Hot Swap

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

Chapter 5Library Services

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Functional Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Control Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Control Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

NaiControlRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

NaiControlWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

VTTY Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

NaiVttyRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

NaiVttyWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

NaiSetVTTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

NaiClearVTTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Data Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11

NaiDataRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11

NaiDataWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

NaiTxHalt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

NaiTxResume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

NaiRxHalt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

NaiRxResume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16Device Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

NaiOpenAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

NaiRunDiags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18

NaiCloseAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

NaiResetAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20

NaiDownloadAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21

NaiReadCrashData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22

NaiOpenChannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23


7/110

Brooktrout Driver Programmers Manual vii

Table of Contents

NaiCloseChannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24

NaiSetMgmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25

NaiSetPulse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26

Appendix ABrooktrout Customer Support

Customer First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Before You Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Information About Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Contacting Brooktrout Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

Additional Brooktrout Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Appendix BUsing the Virtual TTY Diagnostic Port Program

Starting the Virtual TTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Displaying Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Viewing the Diagnostics Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4

Version String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4

Give/Take Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4Control Message Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5

Interrupt Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5

Tracing Link Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6

Running a Level 1 Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6

Running a Level 2 Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8

Interpreting the I Frame Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9

Interpreting the Message Headed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-10

Interpreting Information Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11


8/110

viii Brooktrout Driver Programmers Manual

Table of Contents


9/110

List of Figures

Figure 1-1 Driver and Library Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Figure B-1 Memory Map for PCI Boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

Figure B-2 Memory Map for cPCI Boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3Figure B-3 Level 1 Trace Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7

Figure B-4 Level 2 Trace Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9Figure B-5 I Frame Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-10Figure B-6 Message Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11

Figure B-7 IE Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12


10/110


11/110

List of Tables

Table 2-1 Driver Test Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Table 3-1 Driver Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Table 5-1 Control Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1Table 5-2 VTTY Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Table 5-3 Data Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Table 5-4 Device Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Table 5-5 Hot Swap Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Table B-1 Trace Values & Meanings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8Table B-2 Q.931 Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11

Table B-3 Q.931 Information Element Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-13


12/110


13/110

May 2001 1-1

1Overview

Introduction

This P rogrammers Manua l describes the insta llat ion, opera tion and driver utilit ies

provided by Release 7 of the WAN P CI /cPC I OE M Dr iver for Neutrino; this D river releas e

supports the Instant ISD N Softwa re , Relea se 7 family.

This document ha s been designed for Neutrin o syst em developers wh o a re using WAN P CIor cP CI boa rds in t heir applica tion. It a ssumes experience wit h t he Neutrino environment

a nd Neutrino system t ools, the C program ming lan gua ge, and using int elligent contr oller

boa rds in a CompactP CI or P CI -bus environment.

Ha ve the following publicat ions on han d w hen using the QNX Driver:

I nstant I SDN Softwar e SM I Referencedefines the S imple Messa ge Int erface (SMI )

contr ol messages used to implement a dvan ced telecommunica tions and da ta

netw orking services using B rooktrout boar ds.

Appropriate Technical Descr ipt ionfor the boa rd(s) used.

Appropriateinforma tion in the Neutrino documenta tion set.

QNX Driver Architecture and Layout

The QNX Dr iver allows t he applicat ion progra mmer complete access to th e functiona lity of

the Neta ccess Series 7 fa mily of P CI a nd CompactP CI I SD N contr ollers in a Neutrino

environment.

The QNX Driver can s upport a ny nu mber of Neta ccess Series 7 controllers in a single

chassis. Several pa ra meters of the driver can be tuned for optima l use in a given

configura tion. For informa tion about t hese pa ra meters, see Chapter 2.

The driver, as provided, contains two components: the driver itself (devt-nai) and an

interfa ce librar y (nailib.a). Communica tion to t he driver is done thr ough st a nda rd file I/O

ca lls: open()/close(), rea d()/w rit e() for da ta mess a ging a nd dev ctl() for a ll other f unct ionincluding tra nsmit a nd receipt of Inst a nt I SD N SMI contr ol messages.


14/110

1-2 Brooktrout Driver Programmers Manual

Overview

General Operation

It is importa nt t o understa nd tha t operat ions under Neutrino are synchronous.

Operations on a file descriptor (open, close, read, write, devctl) w ill pend unt ilcompleted a nd can not overla p. Tha t is, a read from one process w hich is pending ma y

cause operat ions from a ny other process to pend a s w ell until the original r ead

completes. The QNX driver is designed t o give a developer a w a y t o avoid dea dlock

situa tions like this and t o try an d ma ximize the th roughput of the driver.

For open a nd close processing, the driver t ries to do a s litt le work as possible and

a voids any operat ions th at might cause th is threa d to pend. On close this is not

entirely a voidable. Close processing w ill att empt to disable a channel if the user

application has forgotten to do so. In doing t his, t he close opera tion ma y need to

pend unt il there is room on t he L4L3 SMI q ueue. U nless an a pplica tion ha s opened

ma ny chan nels and subsequently forgott en to issue disables before shutt ing down,

the likelihood of ha ving to w a it for room on t he L4L3 SMI messa ge queue is very

small.

For w rite operat ions, the dr iver ma kes a copy of the da ta to be sent. This a llow s th e

driver to complete t he wr ite operat ion immediat ely therefore a llowing an a pplica tion

to issue multiple w rite operat ions a nd fill the chann els tra nsmit q ueue. It a lso a llows

a n a pplica tion developer freedom over wh ere buffers a re a llocat ed from as there is noimplicit ow nersh ip of th e buffer by t he driver for (potent ia lly) long periods of tim e.

For read operat ions (control or da ta ), the driver ma kes useof the Neutrino pulse mecha nism. This is a service tha t allows t he driver t o send a n a synchronous messageto an applica tion w ith a minimum of da ta (one long word). Thedriver uses this t oindica te to an a pplica tion when (an d wh a t form of) da ta ha s ar rived. One pulse w illbe sent forevery r ead opera tion tha t ca n be immediately completed, soa n applicationcan be simply coded to wa it for pulses a nd issue the appropria te rea d comma nd foreach pulse type tha t can be received. The actual value of the pulses needs t obeconfigur ed a nd ca n be done so per file descriptor (seeChapter 3an d Chapter 5formore information). Neutrinoitself places restr ictions on how pulses can be used,pleaserefer t o the Neutrino documenta tion for deta ils on t his.

Management Stream

The Neut rino driver implements a mult iplexing/demult iplexing of SMI cont rol

messages. This means tha t r esponses to comma nds issued on a pa rticular file

descriptor w ill only be received on tha t file descriptor. How ever, some L3L4 SMI

contr ol messa ges ar e globally applicable. In other cases, it m a y be possible for the

driver to receive messages for which a destina tion file descriptor can not be found (say

a messa ge a rrives la te or loses a r a ce condit ion wit h close processing). To cover for

these cases the Neutrino driver implements t he concept of a m a na gement channel.

Essent ially a ma na gement channel is a channel designa ted to be the recepta cle for a ll

messages that are otherwise undeliverable.

One ma na gement chann el is allowed for ea ch contr oller in the chassis. Any attemptto enable a second mana gement cha nnelw ill be erred (EB U SY). The ma na gementfunction is clea red when the ma nagement stream is closed. I f a ma nagement stream ha s not been declared, a ll messa ges tha t w ould ha ve beendelivered ar e silentlydiscarded.


15/110

Driver Library

May 2001 1-3

Driver Library

The library provides a simplified interface based on functional boundaries: Control,

Da ta , Mana gement a nd a diagnostics connection referred to as th e Virtua l TTY

(VTTY) P ort .

Figure 1-1i l lustr at es the rela tionship of the driver an d the library .

Figure 1-1. Driver and Library Relationship

It is a nticipa ted tha t t he interface library in na ilib.a w ill provide a n early prototype

plat form an d stepping off point for more complex progra mmin g scena rios. The libra ry

is not designed as t he f inal programming API.

Notes

The driver, a s delivered, is not in a n end customerusa ble form. I t is anticipated tha t

a n a pplica tion progra mmer w ill integra te some or a ll of the bina ries provided in t heir

own system integration.

This OE M driver kit includes all source code to a llow free modifica tion a nd

distribution of the driver kit.

Control DataManagement

VTTY

nailib.a

devt-nai

SMI

Message Packets

Device

Payload


16/110


Overview


17/110

May 2001 2-1

2Installation and Operation

Introduction

This cha pter describes how to inst a ll the driver for QNX Neutrino.

Preinstallation RequirementsThe preinsta llat ion requirements for the QNX driver are tha t a B rooktrout P CI car d or

CompactP CI car d be insta lled into your syst em cha ssis; see the appropria te B rooktrout

Technical Description for furth er deta ils on the corr ect insta lla tion of th e controllers. The

syst em requirements a re for 8MB of free disk space.

Installation Overview

Inst a llat ion of the QNX driver is done via t he QNX instal lutility.

Installation and Setup of the QNX Driver for Neutrino

To install the QNX Driver:

1. L og in t o Q NX a s t herootuser andcd to the directory w here you wa nt t he

driver insta lled.

2. Iso9660fsys &to loa d CD driver assume it mounts cd as /cd0

install -u /cd0/naidrv_tar.gz

Note: Alterna tively, if you ha ve obta ined the release from th e Br ooktrout FTP site

(naidrv_tar.gz), you can type 'install -u naidrv_tar.gz'.

3 . When the instal l script a sks if you wa nt to continue, enter y.

4. When Setup is complete, you will need to build the driver a nd sa mple sources to

complete the installation. To do this, enter makeat the comma nd prompt.


18/110


Installation and Operation

Starting the Driver

The driver can be sta rt ed as a background process by t yping: ./devt-nai &a t t he

comma nd prompt. An optional file name pa ra meter can be passed to the driver on

sta rtup. This file must conta in a ssignments of the tuna ble para meters (discussed

further in Chapter 2).

Uninstalling the Driver

B efore insta lling a n ew version of the driver, B rooktrout recommends uninst a lling

the previous driver first .

To uninsta ll the D river:

1. Cha nge directories to where you instal led the driver.

2. I ssue arm -R *.

Running the Driver Test Programs

After driver insta llat ion, tw o directories conta in sa mple test a pplica tions which

demonstr a te usa ge of the QNX driver API:

/test conta ins general unit test progra ms (Table 2-1)

/a tp conta ins a series of test progra ms designed by t he driver review tea m for

a ccepta nce testing.

Table 2-1. Driver Test Programs

Test Name(s) Purpose/Summary

t es t/d ow nloa d A sa m ple of h ow t o d ow n loa d th e a d a pt er .

t est /tes t2

Test /t es t

Downloads the controller a nd a llows a channel to be start ed and da ta to be

sent a nd received.

t es t/vt ty A sim ple vir tu a l t er min a l for th e I IS D N d ia gn ost ic ca r ds. Allow s a ccess t o t he

dia gnostic port on the B rooktrout controller wit hout requiring a physical cable

be plugged into th e diag port.

a t p/t 1_192 C on fig ur e a n d en a ble a ll 192 64K b T1 ch a nn els ; pa s s da t a .

Requires loopback plugs in all spans of the transition module. Supports CPCIcards only.

a t p/e1_248 C on fig ur e a l l 8 spa n s a s E1 a n d en a ble a ll ch a n nels ; pa s ses da t a in loopb a ck

mode.

Requires loopback plugs in all spans of the transition module. Supports CPCI

cards only.

a t p /h 110_256 M a p a l l ch a n n el s t o H .110 b us ; C on fig ur e a s H 110 M a s te r; pa s s da t a .

Requires a n H .110 loopba ck plug (cPCI onl y)


19/110

Running the Driver Test Programs

May 2001 2-3

a t p/t 1_h y8 E n a bles a ll T1 in t er fa ces w it h 3 s uper ch a n nels (8x64k ps ); pa s ses da t a i n

loopback mode. Requires loopback plugs in a ll spans of the tr a nsition module.

Supports CP CI cards only.

at p/sr16h110_256 Maps 256 16Kb subrate channels to the H.110 bus; configures the Brooktrout

board as H .110 Master; pass dat a.

Requires a n H .110 loopback plug (cPCI onl y)

a t p/sr16t 1_256 Maps 256 16Kb channels t o/f rom T1; pass da t a in loopback.

Requires loopback plugs in all spans of the transition module. Supports CPCI

cards only.

t es t/d ow n 2 A s econ d exa m ple of d ow n loa d in g t h e a d a pt er us in g t h e pr ov id ed lib ra r y

t est /smi.c Rea ds a n S MI messa ge a nd does a ra w dump of the da ta

a t p/2boa r ds .c Ver ifies t he oper a tion of 2 boa r ds

a tp/a t p.c A libra ry of common funct ions t o t heATP program sa tp/r256.c Verifies rela y opera t ion on 256 ch annels

a t p/r com plex.c Ver ifi es r ela y oper a t ion on a c om pl exset of rules

a tp/rcopy.c Verifies t he copy opera t ion of rela y

a t p/r defer .c Ver ifies t he defer red oper a tion of r ela y

a t p/r la t mea s.c Th ese t w o a pplica t ion s a r e u sed t omeasure t he latency of the relay module

a t p/r la t wa it .c Th ese t wo a pplica t ion s a re used tomeasure t he latency of the relay module

a t p /t x_r xs m i. c Ver if ies s en di ng /r ecei vi ng S M I m es sa g es

a t p/ud pecho.c Ver ifies opera t ion of U DP l a yera t p/u dpr ela y .c Ver ifi es oper a t ion of U DP i n con ju nct ionwith the relay m odule.

t est /cra sh .c Dumps the I IS DN logout block from a boar d cra sh.

a t p/hy22.c Test s hypercha nnel.

a t p/288.c Open s 288 d a ta ch a nn els an d pa sses da t a . Th is test s g rea t er th a n 256 la pd id s.

/a t p/384.c Open s 384 d a t a ch a n nels a n d pa s ses d a t a . Th is t es ts g rea t er th a n 256 l a pd id s.

/a tp/geo.c This t est geogra phic a ddressing.

/a tp/pkt est .c This is a pa cket t est .

/a t p/r xflood.c F loods th e r eceive q ueue.

/a t p/t xflood.c F loods t he t ra nsm it q ueu e.

/hs/a ut ohs.c S et a uto mode for hot sw ap.

/hs/boot .c B oot s t he a da pt er .

/h s/d ev st a t .c D is pl a ys t h e d evi ce s ta t us . Va r iou s i nf or m a ti on .

/hs/hs.c A libra ry of com mon funct ions t o t he hot sw a p progra ms.

Table 2-1. Driver Test Programs (Continued)



20/110



Tunable Parameters

You ma y need to tune some Brooktrout board para meters to optimize your

a pplica t ion's performa nce or t o elimina te conflict wit h other devices. You can m odify

tuna ble QNX Driver pa ra meters t hrough the use of a configura tion file. I f you modify

para meter values, you must resta rt t he QNX Driver, since the driver reads t his

informa tion only when it is sta rted.

The QNX Dr iver h a s t he following contr ollable pa ra meters. These para meters w ill

rea d from th e config file on th e driver sta rt up only. A sample configura tion file is

provi ded in ./dr iver /config .

The recognized parameters are:

NaiDbgFlags (default of 0; range 0 to 0xffff)

Na iDcha nD escrAddr (defau lt of 0xfe3f9000)

Na iDchanE ventQa ddr (default of 0xfe3fe000)

Na iNumDchan Descr (default of 256 + 32)

Na iNumL34Dcha nEvent (default of 1024)

Na iNumL43Dcha nEvent (default of 0)

Na iNumTXBufs (defa ult of 8; ra nge 3 to 255)

NaiNumRXBufs (default of 8; range 3 to 255)

Na iRXB ufSize (default of 1520; ra nge 2 to 16384)

Na iTXB ufSize (default of 1520; ra nge 2 t o 16384)

Na iLowWat erMarkD efault (default of 2; ra nge 0 to 255)

Na iFilterSt at us (default of 0; ra nge 0 to 1)

Na iP endTxFlow (default of 1; ra nge 0 to 1).

Na iB ufP oolSize (default of 4 meg) This is for II SD N 6.7.59 an d a bove. This

para meter configures the buffer pool size in megabyt es. Ie 4 = 4meg.

Na iHotSw a p (default is 0 = off 1 = on) This para meter tur ns hot sw a p on or off . NaiH otSw ap = 0 The driver will not support hot sw a p

Na iHot Sw a p = 1 The driver hs_type is in H S_AU TO mode

NaiH otSw a p = 2 The driver hs_type is in HS _U SE R mode.

This para meter tur ns hot sw a p on or off .

Ea ch line of the configurat ion file ca n conta in:

A comment (an y line sta rt ing w ith '#')

Bla nk spa ce

/hs/insert .c C all hot sw a p insert IOC TL in user mode.

/h s/q uiesce.c C a ll h ot sw a p q uies ce I OC TL in us er mod e.

/h s/r em ove.c C a ll h ot sw a p r em ove I OC TL in u ser m od e.

/hs/st a t.c D ispla ys t he h ot sw a p st a tus a nd va rious pa ra met er in for ma tion .

/hs/userhs.c S et user mode for hot sw ap.

Table 2-1. Driver Test Programs (Continued)



21/110

Tunable Parameters

May 2001 2-5

An a ssignment

Assignment of a tuna ble ca n be eith er of the following forma ts:

varia ble = valueor

variable value

Varia bles a re not case sensitive. Values ca n be in hex, decima l or octa l.

Examples

Na iRXBufSize = 240

Na iTXBufSize = 512

NaiFil terStatus 1

NaiNumTXBufs 0xF


22/110




23/110

May 2001 3-1

3Driver Services

Introduction

This cha pter describes t he Driver services a vaila ble to the a pplica tion thr ough Neutrino

syst em ca lls. Table 3-1lists each service and describes its purpose; the services are listed

in a lphabetical order in the subsections tha t follow.

Table 3-1. Driver Services

Service Purpose

Devct l IOCTL_NAI_RE S E T H a lt s a n a da pt er . No input .

IOCTL_NAI_S END_S RE CORD D ow nloa ds ACS II S-records from the

IISDN bootfile to the WAN controller.

IOCTL_NAI_S E T_VTTY Iden t ifies t h is ha ndle a s a VTTY

recipient.

IOCTL_NAI_C LE AR_VTTY Removes t his ha ndle a s t he VTTY

recipient.

IOCTL_NAI_VTTY_RE AD Rea ds da t a from t he VTTY da t a buffera rea .

IOCTL_NAI_VTTY_WRITE Writ es da ta to t he VTTY; da ta buffer

a rea .

IOCTL_NAI_C TL_RE AD Rea ds a n S MI cont rol queue en try; da t a

buffer is input.

IOCTL_NAI_CTL_WRITE Writ es a n S MI control queue; da t a buffer

is input.

I OC TL _N AI _R E AD _C R AS H _D ATA R ea d t h e log ou t block , in t er r upt s t a t us

block and other pertinent crash

informa tion of an ada pter; used for IIS DNdebugging.

IOCTL_NAI_D E B U G S et s t he driver debug bit ma sk, w hich

contr ols t he level of debug messa ges

printed by the driver a t run t ime.

I OC TL_NAI _G E T_AD AP _I NF O R et ur ns inform at ion a bout t he select ed

adapter .

I OC TL_NAI _G E T_S TR M_I NF O Ret ur ns in for ma t ion a bout t his h an dle;

dat a buffer is input .


24/110


Driver Services

Devct l IOC TL_NAI_S E T_D CH AN Alloca t es a pa rt icula r da ta cha nnel

descriptor n umber to t his ha ndle.

IOC TL_NAI_RU N_TE S T Init ia t es a dia gnost ic self test on t he

adapter .

IOC TL_NAI_TX_H ALT H a lt s t he t ra nsmit da t a pump on t his

handle.

IOC TL_NAI_TX_RE S U ME Re-init ia t es t he t ra nsmit da t a pump on

this channel.

IOC TL_NAI_RX_HALT S t ops t he receive da t a pump on th is

handle

IOC TL_NAI_RX_RE S U ME Resumes t he receive da t a pump on t his

handle.

I OC TL_NAI _S E T_L OW_WATE R S et s t he Low w a ter ma rk for th is d at a

channel.

IOC TL_NAI_S E T_P ULS E Indica t es t o t he driver w hich Cha nnel ID

should receive pulses for events on t his

ha ndle. Also defines wha t t he pulse

va lues should be for a ll pulse types used

by the dr iver.

IOC TL_NAI_S E T_MG MT Ident ifies t h is ha ndle a s being t he one

tha t should receive all global or otherw ise

undeliverable L3L4 SMI messages.

IOC TL_NAI_HS _G ET_STATU S Display s board level a nd hot swa p

information.

IOC TL_NAI_HS _STOP Resets the a da pter.IOC TL_NAI_HS _G ET_DE VICE _STATU S Displa ys a da pter device informa tion.

IOC TL_NAI_HS _QU IE SC E U sed in Hot Sw ap U ser mode. Allow s the

user to quiesce the board for hot swa p

removal.

IOC TL_NAI_HS _U SE R Sets hot sw a p mode to U SE R mode.

IOC TL_NAI_H S_AU TO Set s hot sw a p mode to AU TO mode

IOC TL_NAI_HS _DI SABL E Sets hs_ty pe to HS _NONE

IOC TL_NAI_HS _INS ER T U sed in Hot Sw a p U ser Mode. Allows the

user to insert a card a nd init ialize the

softwa re that supports the ada pter.

IOC TL_NAI_HS _RE MOVE U sed in Hot Sw ap U ser mode. Allow s th e

user to remove a ca rd from the chass is.

IOC TL_NAI_HS _G ROW Not supported a t this time.

Table 3-1. Driver Services

Service Purpose


25/110

IOCTL_NAI_RESET

May 2001 3-3

IOCTL_NAI_RESET

Structure #include "nailib.h "

int devctl(fd,IOCTL_NAI_RESET, NULL, 0, NULL);

int fd;

Usage This ioctl puts th e controller into a ha lted a nd reset st a te. After t his ioctl , thecontroller will only respond to an IOCTL_NAI_SEND_SRECORD.

Example int err;

err = devctl(fd, IOCTL_NAI_RESET, NULL, 0, NULL);

Returns EOK- The car d ha s been reset.


26/110


IOCTL_NAI_SEND_SRECORD

IOCTL_NAI_SEND_SRECORD

Structure #include"nailib.h"

int devctl(fd, IOCTL_NAI_SEND_SRECORD, buffer, length, NULL);

int fd;

char *buffer;

int length;

Usage This ioctl ta kes a buffer conta ining an S-record, converts it t o binary a nd downloads

it t o the B rooktrout a da pter. When it sees a n S -record of S9 or S7, the ioctl w ill sta rt

the controller.

buffer must conta in a single, complete a nd va lid S-Record.

length is th e byte length of the buffer string.

Example int err, len;

err = devctl(fd, IOCTL_NAI_RESET, NULL, 0, NULL);

if (err) exit(-1);

if ((fp = fopen("naid.0", "r")) == NULL) {

printf("Cant open naid.0\n");

return;

}

while (!feof(fp)) {

fgets(buffer, 256. fp);

len = strlen(buffer);

err = devctl(fd, IOCTL_NAI_SEND_SRECORD, buffer, len,NULL);

if (err) {

printf("Cant write to controller.\");

return;

}

}

Returns EOK- A good s-record was received and processed

EINVAL- The S -record given w a s somehow not properly formed

EIO- The ada pter is already running or failed to sta rt .


27/110

IOCTL_NAI_SET_VTTY

May 2001 3-5

IOCTL_NAI_SET_VTTY


int devctl(fd, IOCTL_NAI_SET_VTTY,NULL, 0,NULL);

int fd;

Usage This ioctl identifies a particular file descriptor (fd) as the recipient of any and allVTTY da ta from t he cont roller. It a lso ena bles VTTY processing on th e cont roller.

Note tha t only one fd can be ma rked a s t he VTTY recipient for a given cont roller.

Example int err;

err = devctl(fd, IOCTL_NAI_SET_VTTY, NULL, 0, NULL);

Returns EOK- The VTTY ha s been a ssig ned t o th is fd.

EBUSY- Another fd ha s a lrea dy cla imed th e VTTY.


28/110


IOCTL_NAI_CLEAR_VTTY

IOCTL_NAI_CLEAR_VTTY

Structure Structure

#include"nailib.h"

int devctl(fd, IOCTL_NAI_CLEAR_VTTY,NULL, 0,NULL);

int fd;

Usage This ioctl disa ssocia tes a par ticula r file descriptor a s being the recipient of VTTY dat aa nd d isa bles an y VTTY processing on th e cont roller.

Example int err;

err = devctl(fd, IOCTL_NAI_CLEAR_VTTY, NULL, 0, NULL);

Returns EOK- The VTTY has been released.

EACCES- This fd does not current ly own th e VTTY a nd th erefore ca n t release it.


29/110

IOCTL_NAI_VTTY_READ

May 2001 3-7

IOCTL_NAI_VTTY_READ


int devctl(fd, IOCTL_NAI_VTTY_READ, buffer, length, NULL);

int fd;

char *buffer

int length

Usage This ioctl rea ds VTTY da ta from th e cont roller. For th is ioctl t o succeed, a

IOC TL_NAI_SE T_VTTY mu st ha ve been issued on t his s a me fd. The ioctl w ill ret urn

ENOENT if data is not immediately available.

bufferis where the da ta read w ill be placed.

length is the ma ximum amount of data tha t buffer can conta in. This ioctl w ill

re turn the number of bytes a ctual ly read.

Example char buffer[256];

int length = sizeof(buffer);

int err;

err = devctl(fd, IOCTL_NAI_VTTY_READ, buffer, length, NULL);

if (err < 0) exit(1);

for (i = 0; i < bytes_returned; i++) {

printf("%c", buffer[i]);

}

Returns EOK- VTTY da ta ha s been rea d.EACCES- This fd does not own the VTTY.

ENOENT- There is no VTTY data to read.

EACCES- length of the data received.


30/110


IOCTL_NAI_VTTY_WRITE

IOCTL_NAI_VTTY_WRITE


int devctl(fd, IOCTL_NAI_VTTY_WRITE,buffer, length, NULL);

int fd;

char *buffer

int length

Usage This ioctl w rit es VTTY da ta to t he cont roller. For t his ioctl t o succeed a

IO CTL_NAI_S E T_VTTY mus t ha ve been iss ued on t he sa me fd. The ioctl w ill pend

unt il there is room av a ila ble in the VTTY queue.

fd is the file descriptor on which a previous IOCTL_NAI_SET_VTTY was issued.

'buffer' contains t he dat a to be writt en.

'buffer_length ' is th e number of bytes t o w rit e.

Example char *buffer = "d fe0f0000 40\n";

int length = strlen(buffer);

int err;

err = devctl(fd, IOCTL_NAI_VTTY_WRITE, buffer, length, NULL);

Returns EOK- Da ta w as w ritt en to the VTTY.

EACCES- This fd does n ot ow n t he VTTY.

ENOSPC- There is n o space a va ilable t o wr ite t he VTTY messa ge.


31/110

IOCTL_NAI_CTL_READ

May 2001 3-9

IOCTL_NAI_CTL_READ


int devctl(fd, IOCTL_NAI_CTL_READ,L34msg_buffer,

L34msg_buffer_length,NULL);

int fd;

char *L34msg_buffer;

int L34msg_buffer_length = sizeof(L3_to_L4_struct);

int info;

Usage This ioctl r eads a SMI Control L3L4 messa ge from the L3L4 SMI message q ueue.

fd is th e file descriptor on w hich th e control rea d event is t o occur.

'l34msg_buffer' is t he bu ffer t o receive t he m essa ge int o. 'l34msg_buffer_length ' is t he

length of the buffer a nd should alwa ys be at leas t 512 bytes.

Example L3_to_L4_struct buffer;

int info, err;

err = devctl(fd, IOCTL_NAI_CTL_READ, (char *) buffer,

sizeof(L3_to_L4_struct), &info);

if (err) {

..do error handling..

}

switch (buffer.msgtype) {

case L3L4mALERTING:

....

}

Returns EOK- An L3L4 SMI m essage ha s been rea d.

ENOENT- There ar e no L3L4 SMI m essages wa iting t o be read .

EINVAL- B uffer is not lar ge enough t o hold an L 3L4 message.


32/110


IOCTL_NAI_CTL_WRITE

IOCTL_NAI_CTL_WRITE


int devctl(fd, IOCTL_NAI_CTL_WRITE,L43msg_buffer,

L43msg_buffer_length,NULL);

int fd;

char *L43msg_buffer;

int L43msg_buffer_length = sizeof(L4_to_L3_struct);

int info;

Usage This ioctl w rites a n L4L3 SMI contr ol messa ge to the L4L3 SMI message q ueue.

l43msg_bufferis the L4L3 message buffer to writ e.

l43msg_buffer_length is t he length of the buffer a nd should a lwa ys be 512 byt es.

infodoes not conta in a ny m eaningful da ta upon completion.

Example L4_to_L3_structbuffer;

int info, err;

buffer.msgtype = L4L3mREQ_LINE_STATUS;

err = devctl(fd, IOCTL_NAI_CTL_WRITE, (char *) buffer,

sizeof(L4_to_L3_struct), &info);

Returns EOK- A L4L3 SMI m essage ha s been w ritt en.

ENOMEM- There wa s not enough memory to a llocat e the receive and t ra nsmitbuffers for this pa rt icular L4L3mENAB LE _P ROTOCOL m essage.

ENOSPC- There wa s no space ava ilable on t he L4L3 SMI q ueue for t his messa ge.

EINVAL- Buffer is not lar ge enough t o hold a n L4L3 message.


33/110

IOCTL_NAI_READ_CRASH_DATA

May 2001 3-11

IOCTL_NAI_READ_CRASH_DATA


int devctl(fd, IOCTL_NAI_READ_CRASH_DATA, buffer, length,

NULL);

int fd;

NaiCrashData_t*buffer;

int length = sizeof(NaiCrashDump_t);

Usage This ioctl is used to retrieve informa tion a bout a contr oller crash dump. It is primar ily

used for IIS DN softwa re debugging.

bufferis wh ere to put t he cra sh dump informa tion. length should be a t lea st size of

(NaiCrashDat_t).

Example NaiCrashData_tbuffer;

int err;

err = devctl(fd, IOCTL_NAI_READ_CRASH_DATA, &buffer,

sizeof(NaiCrashData_t), NULL);

Returns EOK- The crash du mp ar ea ha s been read.


34/110


IOCTL_NAI_DEBUG

IOCTL_NAI_DEBUG


int devctl(fd, IOCTL_NAI_DEBUG, debug_value, length, NULL);

int fd;

short *debug_value;

int length;

Usage This ioctl is used t o set t he debug bit m a sk w hich cont rols the level of driver debug

output printed a t run t ime. This ioctl is useful prima rily for driver debugging

purposes only.

Debug bitma sk: values ca n be found in NAILI B .H.

debug_valuepoints t o a short conta ining the bitma sk requested.

length should be 2.

Example short debug_flag = 0x0123;

int err;

err = devctl(fd, IOCTL_NAI_DEBUG, &debug_flag, sizeof(short), NULL);

Returns EOK- The debug fla g ha s been set.


35/110

IOCTL_NAI_GET_ADAP_INFO

May 2001 3-13

IOCTL_NAI_GET_ADAP_INFO


int devctl(fd, IOCTL_NAI_GET_ADAP_INFO, buffer, length, NULL);

int fd;

char *buffer;

int length;

Usage This ioctl returns t he ada pter structure a ssociat ed with t his fd. I t is useful primar ily

for debugging pur poses only.

fd is t he file descriptor on w hich the a da pter informa tion is to occur.

'buffer' is w here to place the a da pter str ucture read.

'length ' must be a t least 'sizeof(Na iAda pter_t)'.

Example NaiAdapter_tbuffer;int err;

err = devctl(fd, IOCTL_NAI_GET_ADAP_INFO, &buffer,

sizeof(NaiAdapter_t), NULL);

Returns EOK- The a da pter str ucture ha s been rea d.


36/110


IOCTL_NAI_GET_STRM_INFO

IOCTL_NAI_GET_STRM_INFO


int devctl(fd, IOCTL_NAI_GET_STRM_INFO, buffer, length, NULL);

int fd;

char *buffer;

int length;

Usage This ioctl returns t he strea m str ucture associat ed with t his fd. I t is useful primar ily

for debugging pur poses only.

fd is t he file descriptor on wh ich t he strea m informat ion event is t o occur.

'buffer' is where to place the strea m st ructure read.

'length' must be at least 'sizeof(NaiStream_t)'.

Example NaiStream_t buffer;int err;

err = devctl(fd, IOCTL_NAI_GET_STRM_INFO, &buffer,

sizeof(NaiStream_t), NULL);

Returns EOK- The strea m st ructure ha s been rea d.


37/110

IOCTL_NAI_SET_DCHAN

May 2001 3-15

IOCTL_NAI_SET_DCHAN


int devctl(fd, IOCTL_NAI_SET_DCHAN,&channel_number,

sizeof(channel_number), NULL);

int fd;

short channel_number;

Usage This ioctl sets (or can be used to reassign) the data channel descriptor number

a ssociat ed with this fd. This value is used to determine wh ich d chann el in th e SMI

the fd wil l read a nd wri te da ta messa ges to and from.

channel_number points to a short containing the actual da ta channel number

(between 0 and 255).

Note: The dat a cha nnel number can a lso be set w hen issuing a nL4L3mENAB LE _P ROTOCOL message.

Note: This mechanism a llow s for t w o fds to claim t he sa me d chann el. This is not asuggested mode of operat ion, but the dr iver d oes not disa llow it.

Example short channel_number = 5;

int err;

err = devctl(fd, IOCTL_NAI_SET_DCHAN, &channel_number,

sizeof(short), NULL);

Returns EOK- The dcha nnel num ber ha s been set.


38/110


IOCTL_NAI_RUN_TEST

IOCTL_NAI_RUN_TEST


int devctl(fd, IOCTL_NAI_RUN_TEST, NULL, 0, NULL);

int fd;

Usage This ioctl is used t o sta rt th e diag nostic P OS T (P ower On S elf Test).

Example int err;

err = devctl(fd, IOCTL_NAI_RUN_TEST, NULL, 0, NULL);

Returns EOK- The POS T test w a s sta rt ed.

EIO- The P OS T fa iled.


39/110

IOCTL_NAI_TX_HALT

May 2001 3-17

IOCTL_NAI_TX_HALT


int devctl(fd, IOCTL_NAI_TX_HALT,NULL, 0,NULL);

int fd;

Usage This ioctl is used to stop th e tra nsmission of dat a on a given fd. Insta nt I SD N w ill stoptra nsmitt ing dat a a s soon a s the current buffer tra nsmission is complete. The ioctl

w ill not complete until IIS DN ha s acknowledged tha t t ra nsmission ha s been ha lted.

Example int err;

err = devctl(fd, IOCTL_NAI_TX_HALT, NULL, 0, NULL);

Returns EOK- The tra nsmit st ream h a s been ha lted.


40/110


IOCTL_NAI_TX_RESUME

IOCTL_NAI_TX_RESUME


int devctl(fd, IOCTL_NAI_TX_RESUME, NULL, 0, NULL);

int fd;

Usage This ioctl is used to resta rt the tr a nsmission of data on a given fd a fter it ha s beenstopped by a n I OCTL_NAI_TX_HALT ioctl. Inst a nt ISD N w ill sta rt tra nsmitt ing

da ta immediately upon receiving t his call . The ioctl will not complete unt il IIS DN h a s

acknowledged t hat tra nsmission ha s been resta rted.

Example int err;

err = devctl(fd, IOCTL_NAI_TX_RESUME, NULL, 0, NULL);

Returns EOK- The tra nsmit st ream h as been resta rt ed.


41/110

IOCTL_NAI_RX_HALT

May 2001 3-19

IOCTL_NAI_RX_HALT


int devctl(fd, IOCTL_NAI_RX_HALT, NULL, 0,NULL);

int fd;

Usage This ioctl is used to stop the reception of dat a on a given fd. Inst a nt ISD N w ill stopreceiving da ta a s soon a s t he current da ta buffer ha s been received. The ioctl will not

complete until Insta nt I SD N has a cknowledged that reception has been ha lted.

Example int err;

err = devctl(fd, IOCTL_NAI_RX_HALT, NULL, 0, NULL);

Returns EOK- The receive str eam ha s been ha lted.


42/110


IOCTL_NAI_RX_RESUME

IOCTL_NAI_RX_RESUME


int devctl(fd, IOCTL_NAI_RX_RESUME, NULL, 0, NULL);

int fd;

Usage This ioctl is used t o resta rt the reception of dat a on a given fd a fter it ha s been st oppedby a n IOC TL_NAI_RX_HALT ioctl. Insta nt ISD N w ill sta rt receiving da ta

immediat ely upon r eceiving t his call . The ioctl w ill not complete unt il IIS DN ha s

a cknowledged tha t r eception has been restar ted.

Example int err;

err = devctl(fd, IOCTL_NAI_RX_RESUME, NULL, 0, NULL);

Returns EOK- The receive strea m ha s been resta rt ed.


43/110

IOCTL_NAI_SET_LOW_WATER

May 2001 3-21

IOCTL_NAI_SET_LOW_WATER


int devctl(fd, IOCTL_NAI_SET_LOW_WATER_MARK, &water_mark,

sizeof(water_mark), NULL);

short water_mark=2;

int err;

Usage This ioctl resets t he IISD N da ta channel descriptor low wa ter ma rk for contr olling the

number of tra nsmit complete interrupt s (for m ore informa tion, refer t o the SMI

Programmer s G uide). A defa ult va lue is set w hen th e fd is opened (va lue depends on

the current driver t unable para meter LowWaterMark).

'wa ter_ma rk' points to a short va lue conta ining the r equested level.

'length' should be 2.

Example short water_mark=2;

int bytes;

err=devctl(fd, IOCTL_NAI_SET_LOW_WATER_MARK, &water_mark,

sizeof(water_mark), NULL)) {

Returns EOK- The low wa ter ma rk ha s been reset.


44/110


IOCTL_NAI_SET_MGMT

IOCTL_NAI_SET_MGMT


int devctl(fd, IOCTL_NAI_SET_MGMT, NULL, 0,NULL);

int fd;

Usage This ioctl is used to identify a par ticula r file descriptor as being t he one wh ich shouldreceive a ll SMI messages tha t a re global in na tur e are otherwise not delivera ble.

Example int err;

err = devctl(fd, IOCTL_NAI_SET_MGMT, NULL, 0, NULL);

Returns EOK- The ma na gement channel str eam ha s been ma rked.

EBUSY- Another strea m ha s alr eady claimed the ma na gement role.


45/110

IOCTL_NAI_SET_PULSE

May 2001 3-23

IOCTL_NAI_SET_PULSE

Structure #include "nailib.h"

int devctl(fd, IOCTL_NAI_SET_PULSE, &pulse, sizeof(pulse),

NULL);

NaiPulse_t pulse;

Usage This ioctl associat es a given C ha nnel ID w ith a file descriptor and defines the pulsecode values tha t w ill be used to indica te th e arr ival of SMI Contr ol da ta , VTTY dat a

or Received data on a da ta channel descriptor. The driver will use the given C ha nnel

ID to crea te a connection to th e applica tion on which it will send t hese pulses to

indica te the ar rival of new w ork.

Example

#define CONTROL_PULSE_CODE 0x11 // arbitrary

#define VTTY_PULSE_CODE 0x22 // choices#define DATA_PULSE_CODE 0x33

int err;

NaiPulse_t pulse;

pulse.chid = ChannelCreate(_NTO_CHF_UNBLOCK |_NTO_CHF_DISCONNECT);

if (pulse.chid == -1) exit(1);

pulse.ctl_pulse = CONTROL_PULSE_CODE;

pulse.vtty_pulse = VTTY_PULSE_CODE;

pulse.data_pulse = DATA_PULSE_CODE;

err = devctl(fd, IOCTL_NAI_SET_PULSE, &pulse,

sizeof(pulse), NULL);

Returns EOK- The id has been accepted.


46/110


IOCTL_NAI_HS_GET_STATUS

IOCTL_NAI_HS_GET_STATUS


int devctl(fd, IOCTL_NAI_HS_GET_STATUS, NULL, 0, NULL);

int fd;

Usage This ioctl display s informa tion about t he ada pter including: boa rd t ype, board st a te,bus an d slot, sha red memory ba se, sha red memory length, ma ximum sha red memory

length , i/o memory ba se, i/o memory lengt h, int errupt number , interr upt id, hot s w a p

sta te , hot swa p type, hot swa p control and sta tus register contents .

Example int err;

err = devctl(fd, IOCTL_NAI_HS_GET_STATUS, NULL, 0, NULL);

Returns E OK


47/110

IOCTL_NAI_HS_STOP

May 2001 3-25

IOCTL_NAI_HS_STOP


int devctl(fd, IOCTL_NAI_HS_STOP, NULL, 0, NULL);

int fd;

Usage This ioctl ca lls NaiReset(ad apt er) a nd reset t he a da pter.

Example int err;

err = devctl(fd, IOCTL_NAI_HS_STOP , NULL, 0, NULL);

Returns E OK


48/110


IOCTL_NAI_HS_GET_DEVICE_STATUS

IOCTL_NAI_HS_GET_DEVICE_STATUS


int devctl(fd, IOCTL_NAI_HS_GET_DEVICE_STATUS, NULL, 0, NULL);

int fd;

Usage This ioctl displa ys va rious a da pter device informa tion such a s: vendor id, device id,class codes, revision id, bus number, device number, status register, command

register, header type, B IST, la tency timer, ca che line size, sub vendor id, subsystem

id, ma x lat ency, min gnt , pci interrupt pin, interrupt line, capabilities pointer a nd

B AR 0-3.

Example int err;

err = devctl(fd, IOCTL_NAI_HS_GET_DEVICE_STATUS, NULL, 0, NULL);

Returns E OK


49/110


50/110


IOCTL_NAI_HS_USER

IOCTL_NAI_HS_USER


int devctl(fd, IOCTL_NAI_HS_USER, NULL, 0, NULL);

int fd;

Usage This ioctl set s t he hs_ty pe to U SE R mode. Which a llow s th e user to utilize ioctls t ocont rol hot swa p activity.

Example int err;

err = devctl(fd, IOCTL_NAI_HS_USER, NULL, 0, NULL);

Returns EO K - sw itched to user m ode successfully.


51/110


52/110


IOCTL_NAI_HS_DISABLE

IOCTL_NAI_HS_DISABLE


int devctl(fd, IOCTL_NAI_HS_DISABLE, NULL, 0, NULL);

int fd;

Usage This ioctl turns the hs_type to HS _NONE a nd t urns off hot swa p functionality.

Example int err;

err = devctl(fd, IOCTL_NAI_HS_DISABLE, NULL, 0, NULL);

Returns E OK


53/110

IOCTL_NAI_HS_INSERT

May 2001 3-31

IOCTL_NAI_HS_INSERT


int devctl(fd, IOCTL_NAI_HS_INSERT, NULL, 0, NULL);

int fd;

Usage This ioctl is used for hot sw a p and it should be ca lled a fter th e user has inserted thea da pter into the slot a nd closed the latches. This notifies the softw a re tha t a card is

in the slot and ready for a ctivity. This can be used in hot sw a p US ER mode only.

Example int err;

err = devctl(fd, IOCTL_NAI_HS_INSERT, NULL, 0, NULL);

Returns E OK


54/110


IOCTL_NAI_HS_REMOVE

IOCTL_NAI_HS_REMOVE


int devctl(fd IOCTL_NAI_HS_REMOVE, NULL, 0, NULL);

int fd;

Usage This ioctl is used for hot sw a p an d it should be called after the user ha s quiesced t he.This notifies the softw a re tha t a card is in t he slot a nd rea dy for remova l. This can be

used in hot sw a p US ER m ode only.

Example int err;

err = devctl(fd, IOCTL_NAI_HS_REMOVE , NULL, 0, NULL);

Returns E OK


55/110

May 2001 4-1

4Hot Swap

Introduction

This section describes th e Neta ccess Series 7 QNX/Neutr ino Driver Hot Sw a p (H S)

implementa tions of the driver an d host a pplica tion usage. The Hot Sw ap feat ure is

supported on the NS 300 Compa ctP CI cards only.

Implementation

To activat e this featur e, the user must first set NaiHotSwap = 1in th e config file wh en thedriver is first st a rted. This notifies th e driver to support hotsw a p.

There are tw o wa ys th a t hot sw a p ca n be implement ed. The first is the defa ult setting

which has an AUTOmode. This implementa tion is activa ted a t boot up t ime and it sets t he

hs_ty pe to HS_AUTO. All hot sw a p activity is now t o be contr olled aut oma tically th roughthe dr iver. The driver polls the hot sw a p contr ol and st a tus register every 1.5 seconds. If

there is a cha nge in sta te such a s INS_STATor REM_STATgoes high, the dr iver w ill take

the a ppropriat e action.

On insert ion INS_STAT = 1, the driver w ill re-rea d th e pci-bios informa tion a nd re-a llocat ethe softwa re resources for t he ada pter in w hich time the softw a re will reset. The INS_STATbit w ill then clear a nd w hich will a lso clear t he Blue LED on the a da pter signaling the user

tha t i t is now t ime to boot t he ada pter.

In t he case of REM_STAT = 1, the driver w ill aut oma tically do a q uiesce and remova l. This

w ill de-alloca te t he softw ar e resources a nd ma sk interrupts for t his a da pter. The driver

w ill then clear the REM_STATbit a nd cause the LED to be illumina ted, signaling the user

tha t it is OK to physically remove the a da pter from th e cha ssis.

The second implement a tion of hot sw a p is USERmode. This a llow s th e user to cont rol Hot

Sw a p activity th rough librar y calls. The NaiHsUser()l ibrary call will notify t he driver toset hs_type = HS_USER. See the sa mple applicat ion userhs.cin /hsfor an example.


56/110


Hot Swap

Sample Code from userh.c

/* userhs.c 4/4/01 edl

Switch hs_type to USER mode

parameter: bus and slot

example:

./userhs 1 10

*/

#include

#include

#include

#include

#include "nailib.h"

main(int argc, char **argv)

{

int err,fd, bus, slot;

bus = atoi(argv[1]);

slot = atoi(argv[2]);

fd = NaiOpenAdapter(bus,slot);

if (fd < 0){

printf("Unable to open adapter\n");

return -1;

}

err = NaiHsUser(fd);

if (err)

printf("NaiHsUser err %d\n",err);

return;

}

When t his mode is selected, t he ENUMb i t in the Hot Sw ap control and sta tus registeris tur ned on, thereby disabling the use of the INS_STATand REM_STATbits. When

the user wa nts t o do a removal , they must f irst cal l NaiHsQuiesce(); see example

quiesce.cin /hs. This will mask interrupts and de-allocate resources.


57/110

Introduction

May 2001 4-3

Sample Code from queisce.c

/* queisce.c 4/4/01 edl

Hot Swap Queisce

parameters: bus and slot

example:

./quiesce 1 10

*/

#include

#include

#include

#include

#include "nailib.h"


{





if (fd < 0){


return -1;

}

err = NaiHsQuiesce(fd);

if (err)

printf("NaiHsQuiesce err %d\n",err);

return;

}

Secondly, t he user must call NaiHsRemove(); see the exam ple in remove.cin /hs.This will remove th e ada pter and illuminat e the Blue LED notifying the user tha t it

is now time to physically remove the ada pter from t he cha ssis. When the user wa nts

to insert t he ada pter, this is accomplished by physica lly insert ing the ad apt er and

calling NaiHsInsert(); see insert.cin /hsfor an example. With t his call , the driverw ill unma sk int errupts, r ead pci-bios informa tion, re-a llocate softw a re resources,

clear t he Blue LED a nd reset t he ada pter making i t ready for boot up.


58/110


Hot Swap

Sample Code from remove.c

/* remove.c 4/4/01 edl

Hot Swap Remove


example:

./remove 1 10

*/

#include

#include

#include

#include

#include "nailib.h"


{





if (fd < 0){


return -1;

}

err = NaiHsRemove(fd);

if (err)

printf("NaiHsRemove err %d\n",err);

return;

}


59/110

Introduction

May 2001 4-5

Sample Code from insert.c

/* insert.c 4/4/01 edl

Hot Swap Insert

parameters: bus and slot

example:

./insert 1 10

*/

#include

#include

#include

#include

#include "nailib.h"


{

int err, fd, bus, slot, chid;




if (fd < 0){


return -1;

}

err = NaiHsInsert(fd);

if (err)

printf("NaiHsInsert err %d\n",err);

return;

}

The user ca n r eboot t he car d (see boot.cin /hsfor a n exa mple). To swit ch ba ck toa uto mode, use the libra ry call NaiHsAuto(); see autohs.cin /hsfor a n example.

This clear s t he ENUM, INS_STATand REM_STATbits in the hot swa p control a ndsta tus register , and sets hs_typet o HS_AUTO.


60/110


Hot Swap

Sample Code from autohs.c

/* autohs.c 4/4/01 edl

Switch hs_type to AUTO mode


example:

./autohs 1 10

*/

#include

#include

#include

#include

#include "nailib.h"


{





if (fd < 0){


return -1;

}

err = NaiHsAuto(fd);

if (err)

printf("NaiHsUser err %d\n",err);

return;

}

Turning off Hot Sw ap use wit h the NaiHsDisable() library ca ll will change hs_typet o HS_NONEa nd no hot sw a p activity will be recognized by t he driver.

Utility

There ar e tw o utilities in t he /hsdirectory: devstat.cand stat.c. Botha pplica tions display va rious informa tion about the device an d hot swa p stat es.


61/110


62/110


Hot Swap

Sample Code from stat.c

/* stat.c 4/4/01 edl

Hot Swap Status


example:

./stat 1 10

*/

#include

#include

#include

#include

#include "nailib.h"


{





if (fd < 0){


return -1;

}

err = NaiHsStatus(fd);

if (err)

printf("NaiHsStatus err %d\n",err);

return;

}


63/110

Introduction

May 2001 4-9

Where 1 is th e bus an d 10 is th e slot n umber. The following output will be displa yed

by the driver:

Vendor ID = 1011h

Device ID = 46h

Class_Codes = 6800h

Revision ID = 1hBus Number = 1

Device number = 10

Status Reg = 290h

Command Reg = 117h

Header type = 0h

BIST = 0h

Latencey Timer = 40h

Cache Line Size = 8h

Sub Vendor ID = 11ceh

Subsystem ID = 102h

Max Lat = 20ns

Min Gnt = 2ns

PCI Int Pin = INT 1

Interrupt line = 9

Capabilities Pointer = dch

BAR[0] = fe6ff000h

BAR[1] = dc01h

BAR[2] = fe6fef00h

BAR[3] = fc000000h


64/110


Hot Swap


65/110

May 2001 5-1

5Library Services

Introduction

This chapt er describes the QNX Dr iver L ibrar y a vaila ble for use in applicat ion

development. Table 5-1through Table 5-4l ists each librar y function a nd describes its

purpose; the functions a ppea r in a lphabetical order t hroughout this cha pter.

Table 5-1. Control Messaging

Table 5-2. VTTY Handling

Control Message Handling Purpose

Na iCont rolRea d Rea d a n L3L4 S MI cont rol messa ge from t he a da pt er .

Na iCont rolWrit e Writ e a n L4L3 S MI con t rol messa ge t o t he a da pt er .

VTTY Handling Purpose

Na iVt t yRea d Rea d da ta from t he VTTY port ; useful for dia gnost ic checking

an d a pplicat ion debugging.

Na iVt t yWrit e Writ e dia gnost ic comma nds t o t he VTTY port .

Na iS et VTTY Selects t his ha ndle a s being t he VTTY recipient for t he a da pt er .

Na iC lea rVTTY Relea ses t his pa rt icula r ha ndle a s being t he VTTY recipient for

the ada pter .


66/110


Library Services

Table 5-3. Data Messaging

Table 5-4. Device Management

Table 5-5. Hot Swap Management

Data Handling Purpose

Na iDa ta Rea d D a t a is rea d from t he da ta cha nnel descr ipt or , up t o t he

length of bytes requested.

Na iDa ta Writ e D a ta is w rit t en t o t he da ta cha nnel descr ipt or , up t o t helength of bytes requested.

Na iTxH a lt S t ops a n out going da t a st rea m on t he da t a cha nnel descript or .

Na iTxResume Resta rt s a n out going da ta st rea m on t he da ta cha nnel

descriptor.

Na iRxH a lt S t ops a n incoming da t a st rea m on t he da t a cha nnel

descriptor.

Na iRxResume Resta rt s a n incoming da ta st rea m on t he da ta cha nnel

descriptor.

Device Management Purpose

Na iOpen Ada pt er Opens t he a da pt er a nd a ssocia t es t he file d escr ipt or w it h a

part icular adapter card.

Na iC loseAda pt er C loses a nd relea ses a previously open ha ndle.

Na iReset Ada pt er P la ces a da pt er in a reset mode.

N a iD ow n loa d Ada pt er D ow nloa ds I ns ta n t I S DN soft w a re t o t he a d a pt er .

Na iRea dCra shD at a Rea ds t he cra sh dump a rea on the a da pt er .Na iOpen Ch an nel Opens a n a da pt er an d a ssocia t es a da t a ch an nel d escr ipt or t o t he

selected file descriptor.

Na iC loseC ha nnel C loses a nd relea se a previously open ha ndle.

Na iRunDia gs Init ia lizes dia gnost ic self t est .

Na iS et Mgmt Associa tes t he file descript or a s t he recipient of a ll S MI

ma nagement messages or otherwise lost L 3L4 SMI control

messages.

Na iS et P ulse Set s t he pulse va lue.

Hot Swap Management Purpose

Na iH sAut o(int boa rd) S et s hot sw a p t o H S_AU TO mode

Na iH sD isa ble(in t boa rd ) S et s hot sw a p t o H S_NONE .

Na iH sU ser(int boa rd) S et s hot sw ap t o HS _U SE R


67/110

Introduction

May 2001 5-3

N a iH s Qu ies ce(i nt b oa r d ) R em ov es s of tw a r e r es ou rce s in p repa r a t i on f or a h ot s w a p r em ov a l.

N a iH s R em ov e(i nt b oa r d ) D e-a l loca t e s s of tw a r e r es ou r ces for h ot s w a p rem ov a l.

N a iH s In ser t (in t boa r d) All oca t es soft w a r e r es ou rces for hot sw a p in ser t ion .

Na iH sS ta t us (in t boa r d) D ispla y s va r iou s boa r d st a t us a nd in for ma t ion .

N a iHsDevSt a t us(in t board) Disp lays var ious device level st a t us and in format ion .

Hot Swap Management Purpose


68/110


Library Services

Functional Library

The following section describes the functional interface that is provided with the

driver in a very cursory ma nner.

Control PathThe follow ing subsections illustra te t he function ca lls wh ich a re used for passing SMI

messages to and from th e driver.

Control Messaging

These routines a re used to pass S MI L4L3 and L3L4 messa ges to and from the

adap ter .


69/110

NaiControlRead

May 2001 5-5

NaiControlRead


int NaiControlRead(fd, buffer);

HANDLE fd;

L3_to_L4_struct buffer

Usage This call rea ds a n L3L4 SMI control message from t he ad a pter specified by t he givenha ndle. The call will pend unt il a m essage is a vaila ble.

Example L3_to_L4_struct msg;

memset(&msg, 0, sizeof(msg));

if (NaiControlRead(fd, &msg)) {

error_out(Cant read control message.);

}

switch (msg.msgtype) {case L3L4mALERTING:

}

Returns = 0 Success.

> 0 Return code holds error.


70/110


NaiControlWrite

NaiControlWrite


int NaiControlWrite(fd,buffer)

HANDLE fd

L4_to_L3_struct *buffer;

Usage This call w rites a n L3L4 SMI control messa ge to the a da pter specified by t he given

ha ndle. The ca ll will return E NOSP C if there isn t a ny room to wr ite a new cont rol

message.

Example L4_to_L3_struct msg;

memset(&msg, 0, sizeof(msg)):

msg.msgtype = L4L3mREQ_LINE_STATUS;

if (NaiControlWrite(fd, &msg)) {

error_out(Cant write control message.);

}


> 0 Return code holds error.


71/110

VTTY Handling

May 2001 5-7

VTTY Handling

These messa ges ar e used for rea ding, wr iting a nd ma na ging the II SD N VTTY port.

These messages are not supported on WAN adapters.

NaiVttyRead


int NaiVttyRead(fd, buffer, length);

HANDLE fd;

char *buffer;

int *length;

Usage This call r ead s up to length byt es of da ta from the VTTY port on t he ada pter

specified by t he given fd . VTTY da t a is st ored in buffer . U pon completion, length

conta ins the a ctual num ber of bytes read. This call will return ENOE NT if there isnt

any da ta immediate ly ava i lable .

Example Output

char buffer[256];

int length;

length = sizeof(buffer);

if (NaiVttyRead(fd, buffer, &length)) {error_out(Cant read data.);

}

for (i = 0; i < length; i++) {

printf(%c, buffer[i]);

}


> 0 Failed. Return code holds error.


72/110


NaiVttyWrite

NaiVttyWrite


int NaiVttyWrite(fd, buffer, length);

HANDLE fd;

char *buffer;

int *length;

Usage This call w rit es up to length byt es of da ta to th e VTTY port on the a da pter specified

by th e given fd . Dat a is s tored in buffer . U pon c

Documents

Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI