xalyo systems software manual 0.95

XALYO SYSTEMS, SARL

Xalyo Systems - Ch. Le Grenier 9 - 1291 Commugny - Switzerland

Tel +41 22 776 6177 - Fax +41 22 776 6175 - Mobile +41 79 411 0919 - [email protected] - www.xalyo.com

SOFTWARE-UM

SOFTWARE USERS MANUAL

Users Manual Version 0.95

July 2005

XALYO SYSTEMS

Generic Software for XS PMCs

2

Information in this document is subject to change without notice 2003-2005 Xalyo Systems. All rights reserved. Reproduction of this manual is only allowed for internal use if the user has purchased the Xalyo Systems product described herein. In other cases no part of this publication may be copied in any form without the prior written permission of Xalyo Systems. Trademarks used in this manual: VxWorks is a trademark of Wind River, WinPath is a trademark of Wintegra, Pentium is a trademark of Intel Corporation, and PowerSpanII is a trademark of Tundra Semiconductor Corp. Other trademarks and trade names may be used in this document to refer to either the entities claiming the marks and names of their product. Xalyo Systems disclaims any proprietary interest in trademarks and trade names other than its own. For any enquiry, please contact

Xalyo Systems Grenier 9

1291 Commugny Switzerland

Phone: +41 22 776 61 75

Fax: +41 22 776 61 75 www.xalyo.com

[email protected]

XALYO SYSTEMS


3

END-USER LICENSE AGREEMENT FOR XALYO SYSTEMS SOFTWARE

License Agreement ("Agreement") This license agreement governs Xalyo Systems software ("Software"). Installation of the Software constitutes acceptance of the terms of this License Agreement. Grant of License: Subject to the terms and conditions of this Agreement, Xalyo Systems hereby grants you a limited, nonexclusive license to install and use the source and object code version of the Software for use only on equipment containing a Xalyo Systems product. Limitations: The Software is licensed, not sold, to you. You must retain all copyright and related notices of XALYO SYSTEMS' ownership and other rights in the Software in the product, labeling and documentation provided. Furthermore, you may not: (a) modify, translate, de-compile, reverse engineer, disassemble or otherwise decode the Software; (b) copy any of the Software other than as reasonably required for your company use of the Software in accordance with this Agreement; or (c) sublicense, sell, rent, lend, transfer, post, transmit, distribute or otherwise make the Software available to anyone else, except that you may permanently transfer the Software and accompanying materials provided you retain no copies and the recipient agrees to the terms of this Agreement. Support: Xalyo Systems reserves the right to modify the Software from time to time without obligation to notify you, or any other person or organization of such revision or change. Third Party Licenses: Certain components of this software are provided under license from third party companies. These components may be copied, modified and incorporated into materials for internal company use and in advertising and promotional materials for you or your clients. You are not permitted to use the components, or any portions of the components, in any other way. Furthermore, you may not use the components in any manner which is defamatory or otherwise violates any applicable laws. You may not make copies, either digital or printed, of the components for the purpose of re-licensing or reselling the components (whether separately or in combination with other components) or for any other purpose except those expressly set forth above. Limitation of Liability: IN NO EVENT WILL XALYO SYSTEMS BE LIABLE FOR ANY DAMAGES, INCLUDING LOSS OF DATA, LOST OPPORTUNITY OR PROFITS, COST OF COVER OR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, DIRECT OR INDIRECT DAMAGES ARISING FROM OR RELATING TO THE USE OF THE SOFTWARE, HOWEVER CAUSED ON ANY THEORY OF LIABILITY. THIS LIMITATION WILL APPLY EVEN IF XALYO SYSTEMS HAS BEEN ADVISED OR GIVEN NOTICE OF THE POSSIBILITY OF SUCH DAMAGE. THE ENTIRE RISK AS TO THE USE OF THE SOFTWARE IS ASSUMED BY THE USER. BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CERTAIN INCIDENTAL, CONSEQUENTIAL OR OTHER DAMAGES, THIS LIMITATION MAY NOT APPLY TO YOU. Disclaimer of Warranty: TO THE EXTENT PERMITTED BY APPLICABLE LAW ALL XALYO SYSTEMS SOFTWARE, INCLUDING THE COMPONENTS, IS PROVIDED "AS IS" AND WITHOUT EXPRESS OR IMPLIED WARRANTY OF ANY KIND BY EITHER XALYO SYSTEMS OR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION OR DELIVERY OF SUCH SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE. NO COVENANTS, WARRANTIES OR INDEMNITIES OF ANY KIND ARE GRANTED BY XALYO SYSTEMS TO THE USER. Termination: Without prejudice to any other rights, Xalyo Systems may terminate this Agreement if you fail to comply with any term or condition of the agreement. In this case, or if you do not accept the terms of this license, you agree to destroy all copies of the Software in your possession and control. Export Control Obligations: You will not export or re-export any Licensed Software in violation of any law, regulation, order or other governmental requirement.

XALYO SYSTEMS


4

Table of contents 1 Using this manual............................................................................................. 12

1.1 Purpose ......................................................................................................... 12 1.2 Audience........................................................................................................ 12 1.3 Icon conventions............................................................................................ 12 1.4 Typographical convention .............................................................................. 12 1.5 Downloading new firmware, software and documentation ............................. 13

2 Revision history................................................................................................ 14 3 Overview............................................................................................................ 15

3.1 General description........................................................................................ 15 3.1.1 Highlights ......................................................................................................................... 15 3.1.2 Elementary Precautions................................................................................................... 15 3.1.3 Supported Features ......................................................................................................... 15 3.1.4 Features to be implemented ............................................................................................ 16 3.1.5 Driver Implementation...................................................................................................... 16 3.1.6 XSIO ................................................................................................................................ 17

3.1.6.1 Sending commands ................................................................................................ 17 3.1.6.2 Send data................................................................................................................ 17 3.1.6.3 Getting data............................................................................................................. 17 3.1.6.4 Getting PHY alarms ................................................................................................ 18

3.1.7 Performance consideration.............................................................................................. 18 4 Building the driver ............................................................................................ 19 5 Accessing and booting XS cards.................................................................... 20

5.1 Verifying that the card is seen on the PCI bus ............................................... 20 5.1.1 VxWorks........................................................................................................................... 20 5.1.2 Linux ................................................................................................................................ 21

5.2 Loading the driver .......................................................................................... 22 5.2.1 VxWorks........................................................................................................................... 22 5.2.2 Linux ................................................................................................................................ 23

6 WinMon: WinPath Boot Monitor...................................................................... 25 6.1 Overview........................................................................................................ 25

7 Software description ........................................................................................ 26 7.1 Software model .............................................................................................. 26

7.1.1 Standalone Software Model............................................................................................. 26 7.1.2 Split Software Model........................................................................................................ 26 7.1.3 NIC Software Model......................................................................................................... 27

7.2 Tools .............................................................................................................. 28 7.2.1 Standalone....................................................................................................................... 28 7.2.2 VxWorks........................................................................................................................... 28 7.2.3 Linux ................................................................................................................................ 28

7.3 Building and executing Hello World on XS cards ........................................ 28 7.3.1 Overwi.............................................................................................................................. 28 7.3.2 The source code .............................................................................................................. 28 7.3.3 The Makefile .................................................................................................................... 28 7.3.4 Compiling and linking....................................................................................................... 29 7.3.5 Loading the binary object into XS cards host memory .................................................... 30

7.3.5.1 VxWorks.................................................................................................................. 30 7.3.5.2 Linux........................................................................................................................ 31

7.3.6 Running the code............................................................................................................. 32 8 Drivers ............................................................................................................... 34

XALYO SYSTEMS


5

8.1 Driver Overview ............................................................................................. 34 8.2 Generic Driver................................................................................................ 34

8.2.1 Overview.......................................................................................................................... 34 8.2.2 API ................................................................................................................................... 34

8.2.2.1 Driver API................................................................................................................ 34 8.2.2.2 Library API .............................................................................................................. 36

8.2.2.2.1 xs_phy_init() ................................................................................................................... 36 8.2.2.2.2 xs_phy_info().................................................................................................................. 37 8.2.2.2.3 xs_phy_loop() ................................................................................................................. 37 8.2.2.2.4 xs_phy_is_loop()............................................................................................................. 38 8.2.2.2.5 xs_phy_enable().............................................................................................................. 38 8.2.2.2.6 xs_phy_is_enabled() ....................................................................................................... 38 8.2.2.2.7 xs_phy_disable() ............................................................................................................. 39 8.2.2.2.8 xs_phy_status() ............................................................................................................... 39 8.2.2.2.9 xs_phy_alarm() ............................................................................................................... 39 8.2.2.2.10 xs_phy_set_error() .......................................................................................................... 40 8.2.2.2.11 xs_phy_is_error()............................................................................................................ 40 8.2.2.2.12 xs_phy_clocking()........................................................................................................... 41 8.2.2.2.13 xs_phy_framing()............................................................................................................ 41 8.2.2.2.14 xs_phy_scramble().......................................................................................................... 41 8.2.2.2.15 xs_phy_is_scrambled() ................................................................................................... 42 8.2.2.2.16 xs_phy_write() ................................................................................................................ 42 8.2.2.2.17 xs_phy_read() ................................................................................................................. 42 8.2.2.2.18 Data structures ................................................................................................................ 43

8.2.3 Summary of driver options............................................................................................... 45 8.2.4 Examples and Utilities ..................................................................................................... 45

8.2.4.1 xsmipsreset ............................................................................................................. 45 8.2.4.2 xsconsole ................................................................................................................ 46 8.2.4.3 xseepromdump ....................................................................................................... 46 8.2.4.4 xseepromread ......................................................................................................... 47 8.2.4.5 xseepromwrite......................................................................................................... 47 8.2.4.6 xsload...................................................................................................................... 48 8.2.4.7 xsusectimerget ........................................................................................................ 48 8.2.4.8 xsphymonitor........................................................................................................... 48

8.3 ATM & Ethernet driver ................................................................................... 50 8.3.1 Overview.......................................................................................................................... 50 8.3.2 Buffer Partitioning ............................................................................................................ 50 8.3.3 Quality of Service............................................................................................................. 52 8.3.4 Interworking ..................................................................................................................... 52 8.3.5 ARP.................................................................................................................................. 54 8.3.6 API ................................................................................................................................... 55

8.3.6.1 xsAtmBind()............................................................................................................. 55 8.3.6.2 xsAtmUnbind() ........................................................................................................ 55 8.3.6.3 xsAtmSend() ........................................................................................................... 55 8.3.6.4 xsAtmSendBlock()................................................................................................... 56 8.3.6.5 xsAtmCallBack()...................................................................................................... 56 8.3.6.6 xsAtmVcStats() ....................................................................................................... 57 8.3.6.7 xsAtmDevStats() ..................................................................................................... 57 8.3.6.8 xsAtmVersion()........................................................................................................ 57 8.3.6.9 xsAtmError()............................................................................................................ 58 8.3.6.10 xsAtmOamVPCreate() ............................................................................................ 58 8.3.6.11 xsAtmOamVPDelete()............................................................................................. 58 8.3.6.12 xsAtmOamSend().................................................................................................... 59 8.3.6.13 xsAtmOamCallBack().............................................................................................. 59 8.3.6.14 xsGetHwInfo() ......................................................................................................... 60 8.3.6.15 xsIwCreate()............................................................................................................ 60 8.3.6.16 xsIwDelete() ............................................................................................................ 61 8.3.6.17 xsGenetEnablePort()............................................................................................... 61 8.3.6.18 xsGenetSend() ........................................................................................................ 61 8.3.6.19 xsGenetBlock()........................................................................................................ 62

XALYO SYSTEMS


6

8.3.6.20 xsGenetCallBack() .................................................................................................. 62 8.3.6.21 xsGenetStats() ........................................................................................................ 63 8.3.6.22 xsGenetError() ........................................................................................................ 64 8.3.6.23 xsGenetMacAdrs() .................................................................................................. 64 8.3.6.24 xsGenetReadPhy().................................................................................................. 64 8.3.6.25 xsGenetWritePhy().................................................................................................. 65 8.3.6.26 xsArpRequest() ....................................................................................................... 65 8.3.6.27 xsArpTableGet()...................................................................................................... 66 8.3.6.28 xsArpEntryAdd()...................................................................................................... 66 8.3.6.29 xsArpEntryDelete().................................................................................................. 66 8.3.6.30 Definitions ............................................................................................................... 67 8.3.6.31 Data Structures ....................................................................................................... 68 8.3.6.32 Globals .................................................................................................................... 75

8.3.7 Summary of driver options............................................................................................... 75 8.3.8 Examples and utilities ...................................................................................................... 76

8.3.8.1 send_aal1................................................................................................................ 76 8.3.8.2 send_aal2................................................................................................................ 76 8.3.8.3 send_aal5................................................................................................................ 77 8.3.8.4 send_raw................................................................................................................. 77 8.3.8.5 send_oam ............................................................................................................... 78 8.3.8.6 receive_aal1............................................................................................................ 79 8.3.8.7 receive_aal2............................................................................................................ 79 8.3.8.8 receive_aal5............................................................................................................ 80 8.3.8.9 receive_raw............................................................................................................. 80 8.3.8.10 receive_oam............................................................................................................ 81 8.3.8.11 xsatmmonitor........................................................................................................... 81 8.3.8.12 perf_aal2 ................................................................................................................. 81 8.3.8.13 get_hw_info............................................................................................................. 82 8.3.8.14 genet_send ............................................................................................................. 82 8.3.8.15 genet_receive.......................................................................................................... 83 8.3.8.16 genet_monitor ......................................................................................................... 83 8.3.8.17 genet_tap ................................................................................................................ 84 8.3.8.18 xsarpmonitor ........................................................................................................... 84 8.3.8.19 xsiwcreate ............................................................................................................... 84

8.4 POS driver ..................................................................................................... 85 8.4.1 Overview.......................................................................................................................... 85 8.4.2 API ................................................................................................................................... 85

8.4.2.1 xsPosEnablePmc().................................................................................................. 85 8.4.2.2 xsPosEnablePort() .................................................................................................. 85 8.4.2.3 xsPosSend()............................................................................................................ 86 8.4.2.4 xsPosBlock() ........................................................................................................... 86 8.4.2.5 xsPosCallBack()...................................................................................................... 87 8.4.2.6 xsPosStats()............................................................................................................ 87 8.4.2.7 xsPosError() ............................................................................................................ 88 8.4.2.8 POS structures........................................................................................................ 88 8.4.2.9 POS globals ............................................................................................................ 89


8.4.4.1 pos_send................................................................................................................. 89 8.4.4.2 pos_receive............................................................................................................. 89 8.4.4.3 pos_monitor ............................................................................................................ 90

8.5 AGA driver ..................................................................................................... 91 8.5.1 Overview.......................................................................................................................... 91 8.5.2 API ................................................................................................................................... 91

8.5.2.1 xsAgaEnablePmc() ................................................................................................. 91 8.5.2.2 xsAgaEnablePort() .................................................................................................. 91 8.5.2.3 xsAgaSend() ........................................................................................................... 92 8.5.2.4 xsAgaBlock() ........................................................................................................... 92 8.5.2.5 xsAgaCallBack()...................................................................................................... 93 8.5.2.6 xsAgaStats()............................................................................................................ 94

XALYO SYSTEMS


7

8.5.2.7 xsAgaError()............................................................................................................ 94 8.5.2.8 Structures................................................................................................................ 94 8.5.2.9 Globals .................................................................................................................... 95


8.5.4.1 aga_send ................................................................................................................ 95 8.5.4.2 aga_receive............................................................................................................. 95 8.5.4.3 aga_monitor ............................................................................................................ 96 8.5.4.4 aga_send_from_file................................................................................................. 96 8.5.4.5 aga_analyze............................................................................................................ 97

9 Bibliography...................................................................................................... 98 10 Glossary ......................................................................................................... 99

XALYO SYSTEMS


8

List of Tables Figure 5-1: PCI Windows ..................................................................................................................................... 20 Figure 5-2: PCI window mapping code for sysLib.c ............................................................................................ 22 Figure 7-1: Standalone Software Model ............................................................................................................... 26 Figure 7-2: Split Software Model ......................................................................................................................... 27 Figure 7-3: NIC Software Model .......................................................................................................................... 27 Figure 8-1: Supported ioctls.................................................................................................................................. 36 Figure 8-2: xs_phy_init ......................................................................................................................................... 37 Figure 8-3: xs_phy_info........................................................................................................................................ 37 Figure 8-4: xs_phy_loop ....................................................................................................................................... 37 Figure 8-5: xs_phy_is_loop................................................................................................................................... 38 Figure 8-6: xs_phy_enable.................................................................................................................................... 38 Figure 8-7: xs_phy_is_enabled ............................................................................................................................. 39 Figure 8-8: xs_phy_disable ................................................................................................................................... 39 Figure 8-9: xs_phy_status ..................................................................................................................................... 39 Figure 8-10: xs_phy_alarm ................................................................................................................................... 40 Figure 8-11: xs_phy_set_error .............................................................................................................................. 40 Figure 8-12: xs_phy_is_error................................................................................................................................ 41 Figure 8-13: xs_phy_clocking............................................................................................................................... 41 Figure 8-14: xs_phy_framing................................................................................................................................ 41 Figure 8-15: xs_phy_scramble.............................................................................................................................. 42 Figure 8-16: xs_phy_is_scrambled ....................................................................................................................... 42 Figure 8-17: xs_phy_write .................................................................................................................................... 42 Figure 8-18: xs_phy_read ..................................................................................................................................... 43 Figure 8-19: XS_PHY_CLOCKING .................................................................................................................... 43 Figure 8-20: XS_PHY_FRAMING ...................................................................................................................... 43 Figure 8-21: XS_PHY_FRACTION..................................................................................................................... 43 Figure 8-22: XS_SONET_SDH_STATS.............................................................................................................. 44 Figure 8-23: XS_TDM_STATS............................................................................................................................ 44 Figure 8-24: XS_PHY_STATS............................................................................................................................. 44 Figure 8-25: XS_PHY_STATUS.......................................................................................................................... 45 Figure 8-26: AAL5 to IP/UDP interworking example .......................................................................................... 53 Figure 8-27: Dynamic Ethernet/IP/UDP field update ........................................................................................... 53 Figure 8-28:ARP table example............................................................................................................................ 54 Figure 8-29: xsAtmBind ....................................................................................................................................... 55 Figure 8-30: xsAtmUnbind ................................................................................................................................... 55 Figure 8-31: xsAtmSend ....................................................................................................................................... 56 Figure 8-32: xsAtmSendBlock.............................................................................................................................. 56 Figure 8-33: xsAtmCallBack ................................................................................................................................ 57 Figure 8-34: xsAtmVcStats................................................................................................................................... 57 Figure 8-35: xsAtmDevStats................................................................................................................................. 57 Figure 8-36: xsAtmVersion................................................................................................................................... 58 Figure 8-37: xsAtmVersion................................................................................................................................... 58 Figure 8-38: xsAtmOamVPCreate ........................................................................................................................ 58 Figure 8-39: xsAtmOamVPDelete ........................................................................................................................ 59 Figure 8-40: xsAtmOamSend ............................................................................................................................... 59 Figure 8-41: xsAtmOamCallBack......................................................................................................................... 60 Figure 8-42: xsGetHwInfo .................................................................................................................................... 60 Figure 8-43: xsIwCreate........................................................................................................................................ 60 Figure 8-44: xsIwCreate........................................................................................................................................ 61 Figure 8-45: xsGenetEnablePort ........................................................................................................................... 61 Figure 8-46:xsGenetSend...................................................................................................................................... 62 Figure 8-47:xsGenetBlock .................................................................................................................................... 62 Figure 8-48:xsGenetCallBack............................................................................................................................... 63 Figure 8-49:xsPosStats.......................................................................................................................................... 64 Figure 8-50:xsGenetError ..................................................................................................................................... 64 Figure 8-51:xsGenetMacAdrs............................................................................................................................... 64 Figure 8-52:xsGenetReadPhy ............................................................................................................................... 65 Figure 8-53:xsGenetWritePhy .............................................................................................................................. 65

XALYO SYSTEMS


9

Figure 8-54:xsArpRequest .................................................................................................................................... 65 Figure 8-55:xsArpTableGet .................................................................................................................................. 66 Figure 8-56:xsArpEntryAdd ................................................................................................................................. 66 Figure 8-57:xsArpEntryDelete.............................................................................................................................. 67 Figure 8-58: ATM API Definitions....................................................................................................................... 68 Figure 8-59: xsAtmPvc_t ...................................................................................................................................... 68 Figure 8-60: xsIPFlow_t ....................................................................................................................................... 69 Figure 8-61: xsArpTableENtry_t .......................................................................................................................... 69 Figure 8-62: xsAal0Stats_t.................................................................................................................................... 69 Figure 8-63: xsAal1Stats_t.................................................................................................................................... 69 Figure 8-64: xsAal2Stats_t.................................................................................................................................... 69 Figure 8-65: xsAal34Stats_t.................................................................................................................................. 70 Figure 8-66: xsAal5Stats_t.................................................................................................................................... 70 Figure 8-67: xsRawStats_t .................................................................................................................................... 70 Figure 8-68: xsOamStats_t.................................................................................................................................... 70 Figure 8-69: xsIwStats_t ....................................................................................................................................... 71 Figure 8-70: xsAalStats_t...................................................................................................................................... 71 Figure 8-71: xsAtmVcStats_t................................................................................................................................ 71 Figure 8-72: xsNicStats_t...................................................................................................................................... 71 Figure 8-73: xsAtmDevStats_t.............................................................................................................................. 72 Figure 8-74: xsGenetStats_t.................................................................................................................................. 73 Figure 8-75: xsHwInfo_t....................................................................................................................................... 73 Figure 8-76: xsOamType_t ................................................................................................................................... 75 Figure 8-77: Globals ............................................................................................................................................. 75 Figure 8-78: send_aal1.......................................................................................................................................... 76 Figure 8-79: send_aal2.......................................................................................................................................... 77 Figure 8-80: send_aal5.......................................................................................................................................... 77 Figure 8-81: send_raw .......................................................................................................................................... 78 Figure 8-82: send_oam.......................................................................................................................................... 79 Figure 8-83:receive_aal1....................................................................................................................................... 79 Figure 8-84: receive_aal2...................................................................................................................................... 80 Figure 8-85: receive_aal5...................................................................................................................................... 80 Figure 8-86: receive_raw ...................................................................................................................................... 80 Figure 8-87: receive_oam ..................................................................................................................................... 81 Figure 8-88: xsatmmonitor.................................................................................................................................... 81 Figure 8-89: perf_aal2........................................................................................................................................... 82 Figure 8-90: get_hw_info...................................................................................................................................... 82 Figure 8-91: genet_send........................................................................................................................................ 83 Figure 8-92: genet_receive.................................................................................................................................... 83 Figure 8-93: genet_monitor .................................................................................................................................. 83 Figure 8-94: genet_tap .......................................................................................................................................... 84 Figure 8-95: xsarpmonitor .................................................................................................................................... 84 Figure 8-96: xsiwcreate......................................................................................................................................... 84 Figure 8-97:xsPosEnablePmc ............................................................................................................................... 85 Figure 8-98:xsPosEnablePort................................................................................................................................ 86 Figure 8-99:xsPosSend ......................................................................................................................................... 86 Figure 8-100:xsPosBlock...................................................................................................................................... 87 Figure 8-101:xsPosCallBack................................................................................................................................. 87 Figure 8-102:xsPosStats........................................................................................................................................ 88 Figure 8-103:xsPosError ....................................................................................................................................... 88 Figure 8-104:Structures......................................................................................................................................... 89 Figure 8-105:Globals ............................................................................................................................................ 89 Figure 8-106: pos_send......................................................................................................................................... 89 Figure 8-107: pos_receive..................................................................................................................................... 90 Figure 8-108: pos_monitor.................................................................................................................................... 90 Figure 8-109:xsAgaEnablePmc ............................................................................................................................ 91 Figure 8-110:xsAgaEnablePort ............................................................................................................................. 92 Figure 8-111:xsAgaSend....................................................................................................................................... 92 Figure 8-112:xsAgaBlock ..................................................................................................................................... 93 Figure 8-113:xsAgaCallBack................................................................................................................................ 94

XALYO SYSTEMS


10

Figure 8-114:xsAgaStats....................................................................................................................................... 94 Figure 8-115:xsAgaError ...................................................................................................................................... 94 Figure 8-116:Structures......................................................................................................................................... 95 Figure 8-117:Globals ............................................................................................................................................ 95 Figure 8-118: aga_send......................................................................................................................................... 95 Figure 8-119: aga_receive..................................................................................................................................... 96 Figure 8-120: aga_monitor.................................................................................................................................... 96 Figure 8-121: aga_send_from_file ........................................................................................................................ 96 Figure 8-122: aga_analyze .................................................................................................................................... 97

XALYO SYSTEMS


11

List of Examples Example 5-1: Verifying XS1000 Presence on PCI ............................................................................................... 21 Example 5-2: Verifying XS1000 Presence on PCI ............................................................................................... 21 Example 5-3: Loading the driver object................................................................................................................ 23 Example 5-4: Starting the driver ........................................................................................................................... 23 Example 5-5: Verifying the creation of the device ............................................................................................... 23 Example 5-6: Loading the driver .......................................................................................................................... 23 Example 5-7: Loading the driver .......................................................................................................................... 24 Example 5-8: Verifying the module installation ................................................................................................... 24 Example 5-9: Verifying the driver installation with dmesg .................................................................................. 24 Example 7-1: Hello World Example..................................................................................................................... 28 Example 7-2: Hello World Makefile..................................................................................................................... 29 Example 7-3: Compiling and linking Hello World ............................................................................................... 30 Example 7-4: Loading all utilities to run Hello World.......................................................................................... 30 Example 7-5: Starting the driver and creating the device ..................................................................................... 30 Example 7-6: Connecting to the PCI console ....................................................................................................... 31 Example 7-7: Loading hello.exe in XS card host memory ................................................................................... 31 Example 7-8: Starting the driver ........................................................................................................................... 31 Example 7-9: Connecting to the PCI console ....................................................................................................... 32 Example 7-10: Loading hello.exe in XS card host memory ................................................................................. 32 Example 7-11: Running Hello World on XS card ................................................................................................ 33


XALYO SYSTEMS

12

1 Using this manual

1.1 Purpose The purpose of this document is to describe Xalyo Systems software for developers who intend to develop applications based on XS PMC family.

1.2 Audience It is assumed that the reader of this document is familiar with the C programming language and is experimented installing new hardware and associated device drivers.

1.3 Icon conventions

Warnings: indicates procedures that could be hazardous to your health or cause unpredictable results on the surrounding environment

Cautions: indicates either potential damage to hardware or loss of data and tells you how to avoid the problem.

Notes, hints and tips: indicates important information that helps you make better use of your system

1.4 Typographical convention The following conventions are used throughout this manual:

Program outputs are printed in the Courier New font. Example: The following message appears on your terminal:

No boot device available

Program outputs of special interest are highlighted in green or red Courier New Bold font. Example: -> xsDrv xsInit: Found 1 XS1000 devices Or -> xsDrv XS DRIVER ALREADY INSTALLED

XALYO SYSTEMS


13

Commands you have to enter are printed in Courier New Bold font. Example: You may be instructed to type the following command: tar xvf file.tar

Note that the carriage return at the end of the command is implied and not shown.

Placeholders for which you substitute a value are presented in italics:

Example: Plug the fiber in port x (where x represents the port number designation)

1.5 Downloading new firmware, software and documentation To download the latest firmware software or documentation, please send an e-mail to [email protected] And we will send you a password and instructions to access our protected FTP site. The version of the latest validated software is always mentioned on: www.xalyo.com/support.htm

XALYO SYSTEMS


14

2 Revision history VERSION DATE CHANGES 0.95 July 18, 2005 Initial version, merged all previous software manuals


XALYO SYSTEMS

15

3 Overview

3.1 General description

3.1.1 Highlights XS cards form a family of PCI Telecom Mezzanine Card (PTMC) which offers high-end ATM and IP services. XS cards provide termination, switching and interworking capabilities. As opposed to traditional Network Interface Cards (NIC), XS PMCs have on-board processing which enable them to segment and reassemble ATM & IP traffic in the PMC memory rather than in host memory. Segmenting and reassembling data in host memory often causes the NIC to transfer very short chunks of data (typically 48 bytes for ATM) on the PCI bus. This causes the PCI bus to be fully loaded at relatively low rates (400 mbps). Xalyo Systems has developed a mechanism to transfer data between the PMC and host CPU in a very efficient way, even for minimal packet size. This is explained later in this chapter. We tried to keep the API as simple as possible to shorten the development time for our customers. If you need more functionality, please contact Xalyo Systems. This manual applies to driver version 1.54 and higher.

3.1.2 Elementary Precautions Any electronic device must be handled with caution:

Protect it from mechanical shocks. Protect it from electrostatic discharge (ESD). Do not insert or remove it while the system is powered-on. Plug it on carrier board with care. Dont operate the board when the temperature is below 0C or above 50C.

Xalyo Systems accepts no responsibility for failure, should these conditions not be respected. Refer to the hardware manual corresponding to the card you are using for more details.

3.1.3 Supported Features

AAL0 (Raw ATM cells) termination AAL1 termination AAL2 termination

o CPS o SSSAR o SSTED

AAL5 termination OAM traffic termination

XALYO SYSTEMS


16

Gigabit Ethernet termination Packet over SONET/SDH (POS) termination ATM to IP interworking PHY monitoring and control

3.1.4 Features to be implemented

ATM switching AAL2 switching Bridging IMA SS7 Solaris support

3.1.5 Driver Implementation The driver is available on VxWorks and Linux platform and is composed of:

libraries

The libraries run on the host CPU and provide the various APIs to the user. It is the interface to the driver. On VxWorks, the libraries are linked with the driver. On Linux, the libraries must be linked with the user application.

driver

The driver runs in kernel space on the host CPU. The driver packs and sends all commands to the PMC. The driver also gets and processes events issued from the PMC. There are several driver flavors: ATM

o Generic (AAL0, AAL2, AAL5, Gigabit Ethernet & Interworking) o AAL1 (AAL0, AAL1, AAL2, AAL5)

POS

AGA (ATM Generator and Analyzer). These drivers are described in greater details later in this document.

command server The command server runs on the MIPS CPU on the PMC. It gets command from the host CPU and executes them. The command server is linked with WDDI and interfaces with the Network Processor.

XSIO (Xalyo Systems I/O)

XSIO is a mechanism used to transfer control path commands and data path traffic between the host CPU and the MIPS CPU on the PMC. XSIO is part of the generic driver and is used for all modules (ATM, POS, Ethernet, )

XALYO SYSTEMS


17

XSIO is explained in more details in the next section.

3.1.6 XSIO

3.1.6.1 Sending commands On the host: When a command is issued (xsAtmBind(), xsAtmVcStats(), ), a buffer encoding the command type and its argument is built and DMAed on the PMC. The host then waits for a mailbox to be written by the PMC. This mailbox contains the result code of the command. Optionally, the host will have to issue a DMA to get some parameter (like the xsAtmVcStats_t structure) from the PMC. Eventually the call will end and the routine will return. On the PMC: The PMC is waiting for the end of the DMA containing the command. Then it executes the command and writes the result in a mailbox. The PMC is checking for command every millisecond.

3.1.6.2 Send data On the host: xsAtmSend() will copy the user buffer in a 1 Mbytes transmit buffer. A 16 byte header is prepended to the buffer itself. This header encodes the channel id, the buffer size and some internal parameters. The call returns immediately and the user can re-use the buffer directly. On the PMC: Every millisecond the PMC will generate an interrupt to the host. This will cause the host to DMA the transmit buffer in the PMC memory. When the end of DMA is detected by the PMC, it will start and send all the frames in the buffer.

3.1.6.3 Getting data On the PMC: When frames are received by the PMC, they are copied and stored in a 1 Mbytes receive buffer on the PMC. Every millisecond the PMC will transfer the received buffer in host memory with a DMA transaction. If the receive buffer on the host is not yet available, the DMA is skipped and will be retried at the next millisecond. If the receive buffer on the host is not free, and the receive buffer on the PMC is full, all data in the PMC receive buffer will be discarded. A counter, rxSoftDrop, is incremented. On the Host: When the end of receive buffer DMA is detected by the host (interrupt), the host signals a semaphore. A background task will take over and will call the user provided callback routine for each frame in the buffer.

XALYO SYSTEMS


18

3.1.6.4 Getting PHY alarms On the PMC: When a PHY event occurs, the PMC writes a mailbox. On the Host: An interrupt is generated when the mailbox is written by the MIPS on the PMC. The interrupt signals a semaphore and wakes up a thread in the driver. This thread will then execute and send commands to read/write the PHY in order to find out the cause of the event and clear it.

3.1.7 Performance consideration The XSIO mechanism totally offloads the host CPU, meaning that even for high throughput, the CPU load is very low on the host CPU. Another benefit of XSIO is that the processing on the host is the same for any kind of traffic (AAL2, AAL5). For example, full duplex traffic at OC-3 line rate wont utilize more than 30% of the host CPU, even for AAL2 traffic, leaving more than 70% of the processing power for the user application. The drawback of this solution is that most of the processing is done on the MIPS CPU on the PMC. As the MIPS CPU runs at 200 MHz only, it becomes the bottleneck of the system.

XALYO SYSTEMS


19

4 Building the driver The first step in building the driver is to choose your configuration. This is done through the configure utility in the top level directory. There is a choice of drivers, operating systems and some parameters must be set. Do not rebuild the MIPS software as the MIPS source code is not included in the standard distribution (requires an NDA). This utility generates a .config file. #./configure Which driver? [atm/pos/aga] (pos):atm Which OS? [vxworks/linux] (vxworks): Which Tornado host? [x86-win32/sun4-solaris2] (x86-win32): Do you want to rebuild MIPS software [y/n] (n): finished. Now you can type `make` The next step is to compile the driver which is simply done by typing make. No warnings should be generated. Generally the Makefiles use the Werror flag which causes the compiler to consider warnings as errors. The driver is generated in the objects//x86/drv directory and is called xsDrv.


XALYO SYSTEMS

20

5 Accessing and booting XS cards

5.1 Verifying that the card is seen on the PCI bus XS cards export six windows on the PCI:

BASE ADDRESS REGISTER

OFFSET WINDOW DEFAULT SIZE

0 0x10 I2O 256 KB 1 0x14 PowerSpanII 4 KB 2 0x18 Host memory 16 MB 3 0x1c WinPath 256 KB 4 0x20 Parameter Memory 16 MB 5 0x24 Packet Memory 16 MB

Figure 5-1: PCI Windows Note that not all Host, Parameter and Packet memory range is exported. In normal applications, all data movements are done with the help of the DMA engines which do not require any mapping on the PCI. The memory banks are mapped for debugging purpose only.

Xalyo Systems was not member of PCI-SIG at the time when this manual was written. This means that the PCI Vendor and Device ID are from Tundra Semiconductor. Xalyo Systems is in the process of getting its own PCI Vendor and Device ID.

5.1.1 VxWorks Example 5-1 shows how to verify that the card is seen on the PCI bus and how to get more information about the PCI registers on a CPU running VxWorks: -> pciDeviceShow 0 Scanning function 0 of each PCI device on bus 0 Using configuration mechanism 1 bus device function vendorID deviceID class 00000000 00000000 00000000 00008086 000071a0 00000600 00000000 00000001 00000000 00008086 000071a1 00040600 00000000 00000007 00000000 00008086 00007110 00010600 00000000 00000010 00000000 000010e3 00008261 00800600 00000000 00000011 00000000 00001011 00000046 00800600 00000000 00000012 00000000 00008086 00001229 00000200 00000000 00000013 00000000 00008086 00001229 00000200 value = 0 = 0x0 -> pciHeaderShow 0,0x10,0 vendor ID = 0x10e3 device ID = 0x8261 command register = 0x0106 status register = 0x0230 revision ID = 0x01 class code = 0x06 sub class code = 0x80

XALYO SYSTEMS


21

programming interface = 0x00 cache line = 0x08 latency time = 0xff header type = 0x00 BIST = 0x00 base address 0 = 0x50000008 base address 1 = 0x41000000 base address 2 = 0x42000008 base address 3 = 0x43000000 base address 4 = 0x44000008 base address 5 = 0x45000008 cardBus CIS pointer = 0x00000000 sub system vendor ID = 0x4567 sub system ID = 0x0001 expansion ROM base address = 0x00000000 interrupt line = 0x05 interrupt pin = 0x01 min Grant = 0x00 max Latency = 0x00 value = 0 = 0x0

Example 5-1: Verifying XS1000 Presence on PCI

Note that the XS card can be on a different bus than zero (Try pciDeviceShow x, with x different from 0). The mapping will most likely be different on your system.

5.1.2 Linux Example 5-2 shows how to verify that the card is seen on the PCI bus and how to get more information about the PCI registers on a CPU running Linux: # cat /proc/pci PCI devices found: . . . Bus 3, device 1, function 0: Bridge: PCI device 10e3:8261 (Tundra Semiconductor Corp.) (rev 1). IRQ 17. Master Capable. Latency=32. Prefetchable 32 bit memory at 0xdfec0000 [0xdfefffff]. Non-prefetchable 32 bit memory at 0xff9ff000 [0xff9fffff]. Prefetchable 32 bit memory at 0xde000000 [0xdeffffff]. Non-prefetchable 32 bit memory at 0xff980000 [0xff9bffff]. Prefetchable 32 bit memory at 0xdd000000 [0xddffffff]. Prefetchable 32 bit memory at 0xdc000000 [0xdcffffff]. . . .

Example 5-2: Verifying XS1000 Presence on PCI Note that the mapping will be most likely different on your system.

XALYO SYSTEMS


22

5.2 Loading the driver The next step is to load the driver.

5.2.1 VxWorks VxWorks is not mapping the PCI windows and thus must be done early in the boot process. For this purpose, the user shall copy/paste the following code at the end of the sysHwInit() function in sysLib.c (in your boards BSP). { unsigned int i, bar, busNo, devNo, funcNo, adrs, size, tmp; if(pciFindDevice(0x10E3, 0x8261, 0, &busNo, &devNo, &funcNo) != ERROR) { for(bar=0; bari & 0x000000001) { break; } size *= 2; } sysMmuMapAdd ((void *)((int)adrs & 0xfffffff0), size, VM_STATE_MASK_FOR_ALL, VM_STATE_FOR_IO); } } }

Figure 5-2: PCI window mapping code for sysLib.c

When this is done and that your BSP has been rebuilt, you can load the driver object:

XALYO SYSTEMS


23

-> ld xsDrv xsInit: Found XS-1000 device (device 0) value = 0 = 0x0

Example 5-4: Starting the driver

At this point the driver is installed: -> iosDevShow drv name 0 /null 1 /tyCo/0 1 /tyCo/1 2 /pcConsole/0 2 /pcConsole/1 7 host: 8 /pty/rlogin.S 9 /pty/rlogin.M 8 /pty/telnet.S 9 /pty/telnet.M 11 /vio 12 /dev/xs value = 25 = 0x19

Example 5-5: Verifying the creation of the device

5.2.2 Linux First go to the right directory and load the driver with the provided script: # cd PATH/XS/objects/linux/arch/drv # sh xsload.sh

Example 5-6: Loading the driver

where PATH is the path where the XS directory lies on your server and arch is one of x86 or ppc. You can specify several options when starting the driver, for example set the debug level with:

XALYO SYSTEMS


24

# sh xsload.sh xsDebugLevel=4

Example 5-7: Loading the driver

The script installs the module and creates the device. This can be verified with: # cat /proc/modules xsDrv 246740 0 (unused) soundcore 7044 0 (autoclean) fglrx 188392 0 . . . # cat /proc/devices Character devices: 1 mem 2 pty 3 ttyp 4 ttyS . . . 180 usb 226 drm 254 xs . . .

Example 5-8: Verifying the module installation

and also by looking in /var/log/messages: # dmsg . . . xsInit: Found XS-1000 device (device 0) . . .

Example 5-9: Verifying the driver installation with dmesg


XALYO SYSTEMS

25

6 WinMon: WinPath Boot Monitor

6.1 Overview WinMon is the WinPath monitor running on the MIPS. WinMon has been developed by Wintegra and was ported to XS cards by Xalyo Systems.

Here is a list of addition made by Xalyo Systems: Support of Intel StrataFlash devices

PCI emulated console

The PT4MC standards defines a physical console on the PT4MC connector, but in case the user doesnt have a PT4CC carrier card with a physical console connected to the PT4MC, there is a xsconsole utility which is a way to emulate the console over the PCI bus. For this purpose, PowerSpanII mailboxes 7 and 6 are used to exchange characters from the MIPS to the host CPU and from the host CPU to the MIPS respectively. If the user has a PT4CC carrier card and want to use the real console instead of the PCI emulated console, he must set WinMons BOARD_CONSOLE environment variable to UART. To revert to the PCI console, set BOARD_CONSOLE to PCI. The physical console baud rate is 115200 mbps, 8 bit, no parity, 1 stop bit, no flow control.

Please refer to the WinMon documentation for more details.

XALYO SYSTEMS


26

7 Software description

7.1 Software model There are three software models for XS cards. We will present and discuss each software model in the following sections.

7.1.1 Standalone Software Model In the standalone software model, the user runs his application on the onboard MIPS processor. The host processor is not required and the PMC can be plugged on a simple PMC carrier card. An example of application using this model is an ATM to Ethernet bridge with management done in-band on the Ethernet port.

Figure 7-1: Standalone Software Model

7.1.2 Split Software Model In the split software model, the user can split his application across the MIPS and Host CPU. An example of application using this software model is an ATM to Ethernet bridge with management done out-band via the PCI bus.

XALYO SYSTEMS


27

Figure 7-2: Split Software Model

7.1.3 NIC Software Model In the NIC (Network Interface Card) software model, the user uses one of Xalyo Systems high-level driver and sees the PMC as a NIC. There is no need to develop code for the MIPS in this model. Currently Xalyo Systems can provide the following modules running on VxWorks and Linux (on the Host CPU):

- ATM & Ethernet termination and interworking module - POS termination module - AGA module for ATM Generation and Analysis (test tool)

See the specific sections below for more details on these modules.

Figure 7-3: NIC Software Model

XALYO SYSTEMS


28

7.2 Tools

7.2.1 Standalone A complete suite of tools is available from MIPS to build applications for the on-board MIPS 5Kc. WinMon and standalone applications can be built with these tools. The tools can be downloaded at no charge from www.mips.com.

7.2.2 VxWorks The supported version is be Tornado 2.2 / VxWorks 5.5. Please contact Wind River for more details about Tornado and VxWorks: www.wrs.com

7.2.3 Linux Xalyo Systems is using Linux Montavista 2.1. A Montavista Linux Preview kit is available at no charge at: www.mvista.com/previewkit/index.html

7.3 Building and executing Hello World on XS cards

7.3.1 Overview

7.3.2 The source code Here is the Hello World example: #include int main(int argc, char **argv) { printf("Hello World !\n\r"); return 0; }

Example 7-1: Hello World Example

7.3.3 The Makefile Here is an example Makefile which compiles and links the Hello World application:

XALYO SYSTEMS


29

SET_PATH = PATH=/cygdrive/h/SDELite/sde5.03/bin:/bin; XS_PATH = /cygdrive/w/projects/XS CC = $(SET_PATH) sde-gcc AS = $(SET_PATH) sde-as CPP = $(SET_PATH) sde-cpp CFLAGS = -c -mips32 -nostdinc -fno-builtin -Wall -Wno-main AFLAGS = -c -mips32 LDFLAGS = -mips32 -nostdlib -nostartfiles LINK_FILE = $(XS_PATH)/winmon/target/mips/appl/link.xn INCS = -I$(XS_PATH)/winmon/include C_OBJS = hello.o A_OBJS = start.o OBJS = $(C_OBJS) $(A_OBJS) LIBS = $(XS_PATH)/winmon/lib/mips/libcsde.a HELLO = hello.exe all: $(HELLO) $(HELLO): $(OBJS) $(CC) $(LDFLAGS) -o $(HELLO) -T $(LINK_FILE) $(OBJS) $(LIBS) $(C_OBJS): %.o : %.c $(CC) $(INCS) $(CFLAGS) -o $@ $< $(A_OBJS): %.o : $(XS_PATH)/winmon/target/mips/appl/%.s $(CPP) $(INCS) $< > $

XALYO SYSTEMS


30

PATH=/cygdrive/h/SDELite/sde5.03/bin:/bin; sde-gcc -mips32 -nostdlib -nostartfiles -o hello.exe T/cygdrive/w/projects/XS/winmon/target/mips/ appl/link.xn hello.o start.o/cygdrive/w/projects/XS/winmon/lib/mips/ libcsde.a

Example 7-3: Compiling and linking Hello World

7.3.5 Loading the binary object into XS cards host memory

7.3.5.1 VxWorks First load the driver and all the executables we will use: -> ld ld ld xsDrv xsInit: Found XS-1000 device (device 0) value = 0 = 0x0

Example 7-5: Starting the driver and creating the device Connect the PCI console to get the first free address. Note that the first free address wont change until a new WinMon is loaded into Flash. -> xsconsole MIPS rebooted WinMon version 2.2.1T May 26 2005 15:24:47 All rights reserved (c) 2000-2004 Wintegra Core : WinPath 787-Rev-B0 Wintegra mips5kc Opal Rev 2 Board Id: Xalyo Systems XS-1000 Rev 2 Serial No: 401

XALYO SYSTEMS


31

Detecting flash memory... INTEL STRATAFLASH 28F128 Board parameters: PLL: 400.0Mhz Internal: 0x1f020000, 32 Kbytes @ 200.0Mhz Parameter: 0x08000000, 128 Mbytes @ 100.0Mhz Packet: 0x20000000, 128 Mbytes @ 100.0Mhz Host: 0x00000000, 128 Mbytes @ 66.666Mhz MAC addresses: [eth0] 00:0F:42:00:01:91 [eth1] (null) IP address: 192.168.1.251 Subnet mask: 255.255.255.0 Default gateway: 0.0.0.0 First free address: 0x8004ee28 WinMon>~ value = 0 = 0x0 ->

Example 7-6: Connecting to the PCI console

ow load the file into XS1000 host memory. Note that the ld command that will install the ELF file N

expects to find the file at the first free address plus offset 0x800000. -> xsload 0, "/hello.exe", 0x84ee28) loading file XS/objects/winmon/examples/hello.exe [0x1753 bytes] at offset 0x84ee28 value = 0 = 0x0

Example 7-7: Loading hello.exe in XS card host memory

7.3.5.2 Linux

tart the driver and create the device S # cd XS/objects/linux/x86/drv # sh xsload.sh

Example 7-8: Starting the driver

onnect the PCI console to get the first free address. Note that the first free address wont change C

until a new WinMon is loaded into Flash. # XS/objects/linux/x86/bin/xsconsole MIPS rebooted

XALYO SYSTEMS


32

WinMon version 2.2.1T May 26 2005 15:24:47 All rights reserved (c) 2000-2004 Wintegra Core : WinPath 787-Rev-B0 Wintegra mips5kc Opal Rev 2 Board Id: Xalyo Systems XS-1000 Rev 2 Serial No: 401 Detecting flash memory... INTEL STRATAFLASH 28F128 Board parameters: PLL: 400.0Mhz Internal: 0x1f020000, 32 Kbytes @ 200.0Mhz Parameter: 0x08000000, 128 Mbytes @ 100.0Mhz Packet: 0x20000000, 128 Mbytes @ 100.0Mhz Host: 0x00000000, 128 Mbytes @ 66.666Mhz MAC addresses: [eth0] 00:0F:42:00:01:91 [eth1] (null) IP address: 192.168.1.251 Subnet mask: 255.255.255.0 Default gateway: 0.0.0.0 First free address: 0x8004ee28 WinMon>~ value = 0 = 0x0 ->

Example 7-9: Connecting to the PCI console

ow load the file into XS1000 host memory. Note that the ld command that will install the ELF or N

SREC file expects to find the file at the first free address plus offset 0x800000. # XS/objects/linux/x86/bin/xsload 0, "/hello.exe", 0x84ee28) loading file XS/objects/winmon/examples/hello.exe [0x1753 bytes] at offset 0x84ee28 value = 0 = 0x0

Example 7-10: Loading hello.exe in XS card host memory

7.3.6 Running the code

econnect to the PCI console and load the file. WinMon will recognize and ELF object and will install Rthe segments in memory. -> xsconsole WinMon>ld Hit Cntl-C to exit Found ELF header

XALYO SYSTEMS


33

Loading ELF file from 0xa084ee28 Loading Segment 0 from 0xa084ee5c Copying 0xf30 bytes from 0xa084eea0 to 0x80200000 Loading Segment 1 from 0xa084ee7c Copying 0x100 bytes from 0xa084fdd0 to 0x80200f30 Padding 0x1000 bytes from 0x80201030 Start = 0x80200000, End = 0x80202030 WinMon> Now jump and execute the loaded code. Note that by default go jumps to the start address of the code weve just loaded, in this case 0x80200000. WinMon>go Hello World ! WinMon>

Example 7-11: Running Hello World on XS card

XALYO SYSTEMS


34

8 Drivers

8.1 Driver Overview There are several driver modules available for VxWorks and Linux:

ATM & Ethernet termination and interworking POS termination ATM generator and Analyzer (AGA)

A set of functions is common to all drivers and these functions are described in the Generic Driver section below. The driver is split between the host processor and the MIPS processor on the PMC. Therefore, when the driver is installing, it must load the software on the PMC memory and then instruct the MIPS processor to start its execution. All the process produces some debug display if the driver is started with a debug level higher than 3.

8.2 Generic Driver

8.2.1 Overview There is a set of functionalities which is common to all driver modules. Some of these functionalities doesnt need the MIPS CPU to run at all and some others needs the MIPS CPU to run one of the drivers, but are implemented in all the drivers. Some of these functionalities are listed below:

Reset the MIPS CPU on the PMC Write a string to the PCI console Read a string from the PCI console Load a file into the PMCs memory Read the EEPROMs Write the EEPROMs Enable the SFP optical transceivers Query for SFP optical transceiver presence Read the SFP optical transceiver signature Query for SFP optical transceiver status Select the source of the reference clock Set or read a General Purpose I/O (GPIO) pin on the Wintegra device Read a timer with microsecond resolution on the PMC

All the examples in XS/examples/utils are using these generic functionalities. The API is described in the next section and some examples and utilities using this API are described below. Additionally the generic driver provides physical layer configuration and monitoring. The API is also described below.

8.2.2 API

8.2.2.1 Driver API All the commands to the driver are done through I/O Control (ioctl) commands:

XALYO SYSTEMS


35

ioctl(xs_fd, IOCTL_COMMAND, &command_specific_structure) Below is the list of supported commands and related structures. See XS/include/xsapi.h for up-to-date definitions. The device number argument is the PMC number. If there is only one PMC on your card, this argument shall be set to 0. IOCTL COMMAND VAL

UE ARGUMENT DESCRIPTION

XS_MIPS_RESET 1 XS_VAL_DESC devNo: Device number value: Reset type 0: send a reset pulse 1: keep MIPS in reset

Resets the MIPS processor

XS_CONSOLE_WRITE 2 XS_CONSOLE_BUF_DESC devNo: Device Number buf: string to write bufLen: length of string

Write a string to the PCI console (blocking)

XS_CONSOLE_READ 3 XS_CONSOLE_BUF_DESC devNo: Device Number buf: buffer for string bufLen: max string length

Read a string from the PCI console (blocking)

XS_LOAD_FILE 4 XS_FILE_BUF_DESC devNo: Device Number offset: address in PMC mem buf: buffer len: buffer size

Load a file into XS1000 host memory

XS_EXEC_CMD 5 (internal, not for user) Send a command for execution to the MIPS processor

XS_EEPROM_READ 6 XS_EEPROM_BUF_DESC devNo: Device Number eeprom: eeprom device 0: WinPath EEPROM 1: PowerSpan EEPROM addr: EEPROM address val: pointer to read value

Read a value from an I2C serial Eeprom location

XS_EEPROM_WRITE 7 XS_EEPROM_BUF_DESC devNo: Device Number eeprom: eeprom device 0: WinPath EEPROM 1: PowerSpan EEPROM addr: EEPROM address val: pointer to value to write

Write a value to an I2C serial Eeprom location

XS_DMA_OP 8 (internal, not for user) Does a DMA to or from XS card host, packet or parameter memory

XS_ENABLE_PHY_EVT 9 (internal, not for user) Enables PHY interrupts XS_GET_PHY_EVT 10 (internal, not for user) Wait for a PHY interrupt XS_GET_SERIAL_EVT 11 (internal, not for user) Wait for a serial event from

WinPath XS_PCIBOOT_FILE 12 (internal, not for user) Boots the MIPS over PCI

XALYO SYSTEMS


36

XS_SFP_ENABLE_TX 13 XS_VAL_DESC devNo: Device number port: Port number value : 0 disable, 1 enable

Enables or disables the transceiver Tx optical signal

XS_SFP_PRESENT 14 XS_VAL_DESC devNo: Device number port: Port number value: Result returned here

The value field is set to 1 if the SFP transceiver is present and is set to 0 if the SFP can not be detected. There is a xs_sfp_present() call available in the PHY library (see xsPhy.h)

XS_WPATH_GPIO 17 XS_WPATH_GPIO_DESC Configures a WinPath GPIO pin XS_TEST 18 (internal, not for user) - XS_REFCLK_PRESENT 19 (internal, not for user) - XS_SFP_READ 20 XS_VAL_DESC

devNo: Device number port: Port number value: Byte number when calling the ioctl, result on return.

The value field contains the value of the specified 8-bit register. There is a xs_sfp_byte_value() and a xs_sfp_field_value() call available in the PHY library (see xsPhy.h)

XS_SFP_FAULT 21 XS_VAL_DESC devNo: Device number port: Port number value: Result returned here

The value field is set to 1 if the SFP transceiver detects an internal fault and is set to 0 if the SFP is in good condition. There is a xs_sfp_fault() call available in the PHY library (see xsPhy.h)

XS_SFP_LOS 22 XS_VAL_DESC devNo: Device number port: Port number value: Result returned here

The value field is set to 1 if the SFP transceiver detects a Loss of Signal and is set to 0 if the signal is OK. There is an xs_sfp_los() call available in the PHY library (see xsPhy.h)

XS_US_TIMER 23 - Returns the value of a 32-bit microsecond timer on the PMC

XS_NET_TIMER 24 (internal, not for user) -

Figure 8-1: Supported ioctls

8.2.2.2 Library API

8.2.2.2.1 xs_phy_init() Name: xs_phy_init Synopsis:

#include int xs_phy_init ( int devNo, int mode );

Description: xs_phy_init initializes all physical ports on the specified PMC. Valid modes are: PHY_MODE_NONE 0 Doesnt perform any hardware initialization, but initializes the PHY library.

XALYO SYSTEMS


37

PHY_MODE_ATM 1 Initializes port in ATM mode PHY_MODE_POS 2 Initializes port in POS mode

Returns: N/A

Figure 8-2: xs_phy_init

8.2.2.2.2 xs_phy_info() Name: xs_phy_info Synopsis:

#include int xs_phy_info ( XS_PHY_STATS *stats, int clear, int devno, int port );

Description: xs_phy_info returns physical layer statistics for the specified port in the stats field. If clear is set, statistics counters are cleared.

Returns: 0 on success, -1 on failure

Figure 8-3: xs_phy_info

8.2.2.2.3 xs_phy_loop() Name: xs_phy_loop Synopsis:

#include int xs_phy_loop ( int on, int devno, int port );

Description: xs_phy_loop puts the specified PHY port in loopback mode if on is set. Valid values for on are: LOOPBACK_DISABLED 0 DIAGNOSTIC_LOOPBACK 1 LINE_LOOPBACK 2 PARALLEL_DIAGNOSTIC_LOOPBACK 4


Figure 8-4: xs_phy_loop

XALYO SYSTEMS


38

8.2.2.2.4 xs_phy_is_loop() Name: xs_phy_is_loop Synopsis:

#include int xs_phy_is_loop ( int devno, int port );

Description: xs_phy_is_loop tells if the port is in loopback mode or not.

Returns: 0 if loopback is disabled, 1 if loopback is enabled, -1 on failure.

Figure 8-5: xs_phy_is_loop

8.2.2.2.5 xs_phy_enable() Name: xs_phy_enable Synopsis:

#include int xs_phy_enable ( XS_PHY_STATUS id, int devno, int port );

Description: xs_phy_enable enables the specified interrupt for the specified port.


Figure 8-6: xs_phy_enable

8.2.2.2.6 xs_phy_is_enabled() Name: xs_phy_is_enabled Synopsis:

#include int xs_phy_is_enabled ( XS_PHY_STATUS id, int devno, int port );

Description: xs_phy_is_enabled tells if the an interrupt is enabled on the specified port.

Returns: 0 if the interrupt is disabled, 1if the interrupt is enabled, -1 on failure.

XALYO SYSTEMS


39

Figure 8-7: xs_phy_is_enabled

8.2.2.2.7 xs_phy_disable() Name: xs_phy_disable Synopsis:

#include int xs_phy_disable ( XS_PHY_STATUS id, int devno, int port );

Description: xs_phy_disable disables the specified interrupt for the specified port.


Figure 8-8: xs_phy_disable

8.2.2.2.8 xs_phy_status() Name: xs_phy_status Synopsis:

#include int xs_phy_status ( XS_PHY_STATUS id, int devno, int port );

Description: xs_phy_status returns the status of the specified port.

Returns: 0 if the status is OK, 1 if the status is NOT OK, -1 on failure

Figure 8-9: xs_phy_status

8.2.2.2.9 xs_phy_alarm() Name: xs_phy_alarm Synopsis:

#include int xs_phy_alarm ( void (*rtn)( XS_PHY_STATUS id, XS_PHY_STATUS mask, int no, int port),

XALYO SYSTEMS

Generic

xalyo systems software manual 0.95

Documents

xalyo systems generic

xalyo systems product

xalyo systems grenier

sarl xalyo systems

software available

software b copy

enduser license agreement

internal use