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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
8/110
viii Brooktrout Driver Programmers Manual
Table of Contents
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
10/110
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
12/110
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
16/110
1-4 Brooktrout Driver Programmers Manual
Overview
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
18/110
2-2 Brooktrout Driver Programmers Manual
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)
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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)
Test Name(s) Purpose/Summary
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
20/110
2-4 Brooktrout Driver Programmers Manual
Installation and Operation
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)
Test Name(s) Purpose/Summary
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
22/110
2-6 Brooktrout Driver Programmers Manual
Installation and Operation
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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 .
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
24/110
3-2 Brooktrout Driver Programmers Manual
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
26/110
3-4 Brooktrout Driver Programmers Manual
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 .
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
27/110
IOCTL_NAI_SET_VTTY
May 2001 3-5
IOCTL_NAI_SET_VTTY
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
28/110
3-6 Brooktrout Driver Programmers Manual
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
29/110
IOCTL_NAI_VTTY_READ
May 2001 3-7
IOCTL_NAI_VTTY_READ
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
30/110
3-8 Brooktrout Driver Programmers Manual
IOCTL_NAI_VTTY_WRITE
IOCTL_NAI_VTTY_WRITE
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
31/110
IOCTL_NAI_CTL_READ
May 2001 3-9
IOCTL_NAI_CTL_READ
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
32/110
3-10 Brooktrout Driver Programmers Manual
IOCTL_NAI_CTL_WRITE
IOCTL_NAI_CTL_WRITE
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
33/110
IOCTL_NAI_READ_CRASH_DATA
May 2001 3-11
IOCTL_NAI_READ_CRASH_DATA
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
34/110
3-12 Brooktrout Driver Programmers Manual
IOCTL_NAI_DEBUG
IOCTL_NAI_DEBUG
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
35/110
IOCTL_NAI_GET_ADAP_INFO
May 2001 3-13
IOCTL_NAI_GET_ADAP_INFO
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
36/110
3-14 Brooktrout Driver Programmers Manual
IOCTL_NAI_GET_STRM_INFO
IOCTL_NAI_GET_STRM_INFO
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
37/110
IOCTL_NAI_SET_DCHAN
May 2001 3-15
IOCTL_NAI_SET_DCHAN
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
38/110
3-16 Brooktrout Driver Programmers Manual
IOCTL_NAI_RUN_TEST
IOCTL_NAI_RUN_TEST
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
39/110
IOCTL_NAI_TX_HALT
May 2001 3-17
IOCTL_NAI_TX_HALT
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
40/110
3-18 Brooktrout Driver Programmers Manual
IOCTL_NAI_TX_RESUME
IOCTL_NAI_TX_RESUME
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
41/110
IOCTL_NAI_RX_HALT
May 2001 3-19
IOCTL_NAI_RX_HALT
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
42/110
3-20 Brooktrout Driver Programmers Manual
IOCTL_NAI_RX_RESUME
IOCTL_NAI_RX_RESUME
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
43/110
IOCTL_NAI_SET_LOW_WATER
May 2001 3-21
IOCTL_NAI_SET_LOW_WATER
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
44/110
3-22 Brooktrout Driver Programmers Manual
IOCTL_NAI_SET_MGMT
IOCTL_NAI_SET_MGMT
Structure #include"nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
46/110
3-24 Brooktrout Driver Programmers Manual
IOCTL_NAI_HS_GET_STATUS
IOCTL_NAI_HS_GET_STATUS
Structure #include "nailib.h"
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
47/110
IOCTL_NAI_HS_STOP
May 2001 3-25
IOCTL_NAI_HS_STOP
Structure #include "nailib.h"
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
48/110
3-26 Brooktrout Driver Programmers Manual
IOCTL_NAI_HS_GET_DEVICE_STATUS
IOCTL_NAI_HS_GET_DEVICE_STATUS
Structure #include "nailib.h"
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
49/110
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
50/110
3-28 Brooktrout Driver Programmers Manual
IOCTL_NAI_HS_USER
IOCTL_NAI_HS_USER
Structure #include "nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
51/110
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
52/110
3-30 Brooktrout Driver Programmers Manual
IOCTL_NAI_HS_DISABLE
IOCTL_NAI_HS_DISABLE
Structure #include "nailib.h"
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
53/110
IOCTL_NAI_HS_INSERT
May 2001 3-31
IOCTL_NAI_HS_INSERT
Structure #include "nailib.h"
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
54/110
3-32 Brooktrout Driver Programmers Manual
IOCTL_NAI_HS_REMOVE
IOCTL_NAI_HS_REMOVE
Structure #include "nailib.h"
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
56/110
4-2 Brooktrout Driver Programmers Manual
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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"
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 = 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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
58/110
4-4 Brooktrout Driver Programmers Manual
Hot Swap
Sample Code from remove.c
/* remove.c 4/4/01 edl
Hot Swap Remove
parameter: bus and slot
example:
./remove 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 = NaiHsRemove(fd);
if (err)
printf("NaiHsRemove err %d\n",err);
return;
}
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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"
main(int argc, char **argv)
{
int err, fd, bus, slot, chid;
bus = atoi(argv[1]);
slot = atoi(argv[2]);
fd = NaiOpenAdapter(bus,slot);
if (fd < 0){
printf("Unable to open adapter\n");
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
60/110
4-6 Brooktrout Driver Programmers Manual
Hot Swap
Sample Code from autohs.c
/* autohs.c 4/4/01 edl
Switch hs_type to AUTO mode
parameter: bus and slot
example:
./autohs 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 = 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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
61/110
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
62/110
4-8 Brooktrout Driver Programmers Manual
Hot Swap
Sample Code from stat.c
/* stat.c 4/4/01 edl
Hot Swap Status
parameter: bus and slot
example:
./stat 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 = NaiHsStatus(fd);
if (err)
printf("NaiHsStatus err %d\n",err);
return;
}
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
64/110
4-10 Brooktrout Driver Programmers Manual
Hot Swap
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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 .
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
66/110
5-2 Brooktrout Driver Programmers Manual
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
68/110
5-4 Brooktrout Driver Programmers Manual
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 .
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
69/110
NaiControlRead
May 2001 5-5
NaiControlRead
Structure #include "nailib.h"
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.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
70/110
5-6 Brooktrout Driver Programmers Manual
NaiControlWrite
NaiControlWrite
Structure #include "nailib.h"
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.);
}
Returns = 0 Success.
> 0 Return code holds error.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
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
Structure #include "nailib.h"
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]);
}
Returns = 0 Success.
> 0 Failed. Return code holds error.
8/10/2019 Netaccess Series7 QNXNeutrino DriverManual 800 1015 001 AC PCI
72/110
5-8 Brooktrout Driver Programmers Manual
NaiVttyWrite
NaiVttyWrite
Structure #include "nailib.h"
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
Top Related