application-notes.digchip.comapplication-notes.digchip.com/314/314-68885.pdf · FREESCALE SEMICONDUCTOR CSTHAPG-UG/D REV 13 CSTHAPG-UG/D Rev 13 CONTENTS About This Guide Guide Overview

C-Ware Host Application Programming Guide

C-WARE SOFTWARE TOOLSET, VERSION 2.4

CSTHAPG-UG/DRev 13

© 2004 Freescale Semiconductor, Inc. All rights reserved.

Freescale and the Freescale logo are trademarks of Freescale Semiconductor, Inc.C-3e, C-5, C-5e, C-Port, and C-Ware are also trademarks of Freescale Semiconductor. All other product or service names are the property of their respective owners.

No part of this documentation may be reproduced in any form or by any means or used to make any derivative work (such as translation, transformation, or adaptation) without written permission from Freescale.

Infortmation in this document is provided solely to enable system and software implementers to use Freescale Semiconductor products. There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits based on the information in this document.

Freescale Semiconductor reserves the right to make changes without further notice to any products herein. Freescale Semiconductor makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does Freescale Semiconductor assume any liability arising out the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. “Typical” parameters that may be provided in Freescale Semiconductor data sheets and/or specifications can and do vary in different applications, and actual performance may vary over time. All operating parameters, including “Typicals”, must be validated for each customer application by that customer’s technical experts. Freescale Semiconductor does not convey any license under its patent rights nor the rights of others. Freescale Semiconductor products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the Freescale Semiconductor product could create a situation where personal injury or death may occur. Should Buyers purchase or use Freescale Semiconductor products for any such unintended or unauthorized application, Buyers shall indemnify and hold Freescale Semiconductor and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that Freescale Semiconductor was negligent regarding the design or manufacture of the part.

FREESCALE SEMICONDUCTOR

CSTHAPG-UG/D

Rev 13

CONTENTS

About This GuideGuide Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Using PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Guide Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17References to CST Pathnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Related Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

CHAPTER 1 C-Ware Host Application Programming OverviewIntroducing C-Ware Host Application Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Distinguishing Data Plane From Control Plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25CST Support for Host Application Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Provided Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Support for Static and Dynamic Linkage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Host API Programming Versus Device Driver Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Host Application Development System Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Host Environment/ Hardware NP Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Host Environment/Simulated NP Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Host Environment Simulation/Simulated NP Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Setting Up Tornado for CDS Host Application Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

CHAPTER 2 Building C-Ware Host Application ProgramsBuilding New Software for the CDS Host Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

VxWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Locations of Host Application Software Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Dependencies Among Supplied Drivers and Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Building the C-5 Device Driver Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

VxWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CSTHAPG-UG/D REV 13

4 CONTENTS

Building the VxWorks RTOS Image File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Support for Specific Console Baud Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Support for Dynamically Loadable Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Building the Driver and Linux Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Building the Host API Table Services and Queue Services Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Building the Table and Queue Services Library for VxWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Building the Table and Queue Services Library for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Implementing Extensions to the DCP Shell Command Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Implementing Additional DCP Shell Commands in the C-5 Device Driver . . . . . . . . . . . . . . . . . . . 44Implementing Additional DCP Shell Commands in a DLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Command Specification File Coding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Command Specification Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Command Handler Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Required Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Sample Code for Implementing Command Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Building and Using Statically Linking Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Preferred Entry Point for Host Application User Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Building and Using a Dynamically Linkable Module for the RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Location of DLM Interface Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Coding a DLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Mechanism of DLM Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Support by the DCP Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Standalone Loader for VxWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Loading the Host Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

CHAPTER 3 Host API ProgrammingOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Execution Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Host Services Interfaces to C-5 Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Managing API Global Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

hsCpiFree() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56hsCpiInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

CSTHAPG-UG/D REV 13 FREESCALE SEMICONDUCTOR

CONTENTS 5

Begin/End NP Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58hsCloseDcp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58hsGetDcpHandle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58hsOpenDcp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Host Access to NP Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60hsReadMemory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60hsSeek() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60hsWriteMemory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Programmed I/O Between Host and NP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62hsCloseProtocol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62hsFlushProtocol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62hsOpenProtocol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63hsPeekProtocol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64hsReadProtocol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65hsWriteProtocol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Model of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67DMA Data Transfer Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Mutually Exclusive Sets of Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

hsPktClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68hsPktFree2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68hsPktOpen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69hsPktRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69hsPktRead2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70hsPktSetBtag2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70hsPktSetBuf2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71hsPktSetDesc2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71hsPktWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72hsPktWrite2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73hsClockCalibrate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73hsPackageLoad() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73hsPendOnEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74hsQueryConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74hsReset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75hsSignal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75hsSymbolImport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

FREESCALE SEMICONDUCTOR CSTHAPG-UG/D REV 13

6 CONTENTS

Host-Side C-Ware API Table Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Supported Table Types and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Enabling Remote Procedure Call Functionality on the NP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Host-Side C-Ware API Kernel Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Host API Management of Per-NP Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

CHAPTER 4 Programming the M-5 Channel AdapterOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83The M-5 API Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84m5Init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84m5Open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85m5ChannelConfigOc1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85m5ChannelConfigOc1x48() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86m5ChannelConfigOc3c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87m5ChannelConfigOc3cx16() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87m5ChannelConfigOc12c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88m5ChannelConfigOc12cx4() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88m5ChannelConfigOc48c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89m5CheckFlowSchedTable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89m5SetFlowScheduleTable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Traffic Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90m5ChannelDisable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90m5ChannelEnable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91m5ChannelFifo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91m5FifoChannel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92m5GetStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92m5SetEgressSequenceNo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93m5SetMpsnTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

M-5 Programming Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Example 1: Configuring the M-5 as an Oc-48c channel in Front Port mode . . . . . . . . . . . . . . . . . 94Example 2: Configuring Individual M-5 Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94M-5 Test Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95


CONTENTS 7

CHAPTER 5 Programming the Device DriverOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Device Driver Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98High Level Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Porting Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100System Instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Buffer Management and IPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Low Level Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Bus Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Driver Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Object Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107File Naming Convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107PCI Bus Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Simulator Bus Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Simulator Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Porting and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Porting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Port OSAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Implement OS-specific Kernel Porting Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Implement OS-specific DDK Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Device Driver API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Host Services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Base API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Port Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Packet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Package Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123XP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Low Speed Serial Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127


8 CONTENTS

Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

The Portable Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Linux Driver Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Connecting to the NP Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

CHAPTER 6 Programming Earlier Versions of the C-5 Device DriverOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Software Deliverable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Implementation of the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Driver Data Transfer Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Comparison of Driver Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

PCI Interface Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142NP Base Address Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Four-Byte Data Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Byte Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Memory-Mapped Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Memory Reference By Host Processor to NP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Inbound Address Mapping Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Outbound Address Mapping Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Memory Reference By NP to Host Processor Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Interrupt Functionality Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147NP’s XP Interrupts to the Host Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Asserting an Interrupt to the Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Clearing the Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Host Processor Interrupts to the NP’s XP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Setting a Mailbox Register Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Asserting a Mailbox Register Interrupt to the XP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Executing a Mailbox Register Interrupt Vector Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Clearing a Mailbox Register Interrupt Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149


CONTENTS 9

High Level Public Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Groups of High Level Public Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151dcpTable Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Close a Previously Opened NP Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

dcpMgr::Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Disable XP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

dcpMgr::xpDisable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152DMA Transfer to Host Sense Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

dcpMgr::dmaToHostSenseDone() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153DMA Transfer to NP Sense Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

dcpMgr::dmaToDcpSenseDone() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Enable XP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

dcpMgr::xpEnable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Load Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

dcpMgr::loadPackage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Open a C-Port NP Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

dcpMgr::Open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Pend on Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

dcpMgr::pendOnEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Read Configuration Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

dcpMgr::readCfgMemory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Read Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

dcpMgr::readMemory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Start DMA Transfer to Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

dcpMgr::startDmaToHost() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Start DMA Transfer to NP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

dcpMgr::startDmaToDcp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Write Configuration Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

dcpMgr::writeCfgMemory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Write Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

dcpMgr::writeMemory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163


10 CONTENTS



CSTHAPG-UG/D

Rev 13

FIGURES

1 Distinguishing the Activities Performed on Host Processor and Network Processor . . . . . . 262 Host Environment/Hardware C-Port NP Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 Host Environment/Simulated NP Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Host Environment Simulation/Simulated NP Development . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Host Application Program Dependencies Upon Host Environment Software Libraries . . . . . 376 High Level Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997 IPC Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028 Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049 Device Object Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10510 Bus Object Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10611 Simulator Bus and Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10812 User-defined Packet Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11713 User-defined RPC Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12414 Low-Level Operations for Host Processor to Write to C-Port NP Memory . . . . . . . . . . . . . . 14415 Low-Level Operations for the NP’s XP to Write to Host Processor Memory . . . . . . . . . . . . 146

CSTHAPG-UG/D REV 13

12 FIGURES



CSTHAPG-UG/D

Rev 13

TABLES

1 Navigating Within a PDF Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 C-Ware Host Application Programming Guide Revision History . . . . . . . . . . . . . . . . . . . . . . 193 C-Port Silicon and CST Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Host Application Development Component Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 Table Services Operations Supported for the C-5 On-chip, Host, and Offline APIs . . . . . . . . 786 Table Services Operations Supported for the C-5e & C-3e On-chip, Host, and Offline APIs . 797 OSAL Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108 Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129 Linux Driver Source Code Components and Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13310 Feature Comparison Between the Versions of the C-5 Device Driver . . . . . . . . . . . . . . . . . 141

CSTHAPG-UG/D REV 13

14 TABLES



CSTHAPG-UG/D

Rev 13

ABOUT THIS GUIDE

Guide Overview The C-Ware™ Host Application Programming Guide provides information useful for developers of host applications that integrate with the C-Port C-5, C-5e, and C-3e Network processors.

This guide assumes familiarity with the C-Ware Software Toolset (CST) and either the WindRiver® Systems VxWorks® real-time operating system and its Tornado development environment or the Linux® operating system. It assumes that you are developing a host application targeted to the C-Ware Development System (CDS) environment.

This guide covers the following topics:

• C-Ware Host Application Programming Overview

• Building C-Ware Host Application Programs

• Host API Programming

• Programming Earlier Versions of the C-5 Device Driver

• Host Reference Applications

CSTHAPG-UG/D REV 13

16 ABOUT THIS GUIDE

Using PDF Documents Electronic documents are provided as PDF files. Open and view them using the Adobe® Acrobat® Reader application, version 3.0 or later. If necessary, download the Acrobat Reader from the Adobe Systems, Inc. web site:

http://www.adobe.com/prodindex/acrobat/readstep.html

PDF files offer several ways for moving among the document’s pages, as follows:

• To move quickly from section to section within the document, use the Acrobat bookmarks that appear on the left side of the Acrobat Reader window. The bookmarks provide an expandable ‘outline’ view of the document’s contents. To display the document’s Acrobat bookmarks, press the ‘Display both bookmarks and page’ button on the Acrobat Reader tool bar.

• To move to the referenced page of an entry in the document’s Contents or Index, click on the entry itself, each of which is “hot linked.”

• To follow a cross-reference to a heading, figure, or table, click the blue text.

• To move to the beginning or end of the document, to move page by page within the document, or to navigate among the pages you displayed by clicking on hyperlinks, use the Acrobat Reader navigation buttons shown in this figure:

Beginning of document End of document

Next pagePrevious page

Previous or next hyperlink


www.adobe.com/prodindex/acrobat/readstep.html

Guide Conventions 17

Table 1 summarizes how to navigate within an electronic document.

Guide Conventions The following visual elements are used throughout this guide, where applicable:

This icon and text designates information of special note.

Warning: This icon and text indicate a potentially dangerous procedure. Instructions contained in the warnings must be followed.

Warning: This icon and text indicate a procedure where the reader must take precautions regarding laser light.

This icon and text indicate the possibility of electrostatic discharge (ESD) in a procedure that requires the reader to take the proper ESD precautions.

Table 1 Navigating Within a PDF Document

TO NAVIGATE THIS WAY CLICK THIS

Move from section to section within the document.

A bookmark on the left side of the Acrobat Reader window

Move to an entry in the document’s Contents or Index.

The entry itself

Follow a cross-reference (highlighted in blue text).

The cross-reference text

Move page by page. The appropriate Acrobat Reader navigation buttons

Move to the beginning or end of the document.

The appropriate Acrobat Reader navigation buttons

Move backward or forward among a series of hyperlinks you have selected.

The appropriate Acrobat Reader navigation buttons


18 ABOUT THIS GUIDE

References to CST Pathnames

You typically install the C-Ware Software Toolset (CST) on your development workstation in a directory path suggested by the installation procedure, such as:

• C:\C-Port\Cstx.y\ (on Windows 2000/XP)

• /usr/yourlogin/C-Port/Cstx.y/ (on Sun SPARC Solaris and Linux)

or:

/usr/cport/C-Port/Cstx.y/

or:

/opt/C-Port/Cstx.y/

where ‘x’ is a major version number and ‘y’ is a minor (or intermediate) version number.

You typically install each CST version under some directory path ...\C-Port\Cstx.y\. However, the user can install the CST in any directory on the development workstation. The user can also install more than one CST version on the same workstation.

Therefore, to refer to installed CST directories, we use pathnames that are relative to the ...\C-Port\Cstx.y\ path, which is the “root” of a given CST installation.

For example, the apps\gbeSwitch\ directory path refers to the location of the Gigabit Ethernet Switch application that is installed as part of the CST. The full path of this directory on a Windows 2000/XP system might be C:\C-Port\Cst2.1\apps\gbeSwitch\, so this convention is convenience for shortening the pathname.

Other top-level directories that are installed as part of the CST include bin\, diags\, Documentation\, services\, and so on. These directories are described in the C-Ware Software Toolset Getting Started Guide document, which is part of the CST documentation set.


Revision History 19

Revision History Table 2 provides details about changes made for each revision of this guide.

Note: books in this documentation set began bearing revision numbers in June, 2002. Prior to that date books were identified by CST version number.

Table 2 C-Ware Host Application Programming Guide Revision History

REVISION DATE CHANGES

13 6/2004 This document was revised to replace internal references to ’Motorola’ with ’Freescale Semiconductor’. Copyright Freescale Semiconductor, Inc. 2004.Added new function description, “hsSignal()” on page 75.

12 3/2004 Revised throughout to document support for the new device driver and the Linux operating system.

11 6/20003 Added a Chapter 5, “Programming the Device Driver,” to document the new device driver. The chapter that had borne this title in previous releases became Chapter 6, “Programming Earlier Versions of the C-5 Device Driver.”

10 5/2003 Added Chapter 4, “Programming the M-5 Channel Adapter.”

09 8/2002 In Chapter 2 in the section “Building the VxWorks RTOS Image File”:

• In Step 2 of the procedure, updated the list of Tornado files to modify.

• Segregated other information into two new subsections.

In Chapter 2 renamed an existing section as “Building and Using Statically Linking Modules” and added new content therein. In Chapter 3 updated Table 5 and Table 6.

08 6/2002 Throughout the document, updated references to the C-5 NP to also refer to the C-5e NP and C-3e NP, as appropriate.


20 ABOUT THIS GUIDE

CST 2.1 4/2002 In Chapter 1 in the section “CST Support for Host Application Development”:

• Under the subsection “Provided Components” updated the descriptions of DCP Shell and host application infrastructure.

• Added the new subsection “Support for Static and Dynamic Linkage”.

In Chapter 2 added these new sections:

• “Implementing Extensions to the DCP Shell Command Set”

• “Building and Using Statically Linking Modules”

In Chapter 2 also added these new sections:

• “Preferred Entry Point for Host Application User Code”

• “Building and Using a Dynamically Linkable Module for the RTOS”

In Chapter 3:

• New data types added in the section “Data Types”.

• New introductory text and API routine descriptions added in the section “DMA Data Transfer Operations”.

CST 2.0 9/2001 In Chapter 1 added the new section “Components That Support Wind River’s CPC516 SSP and TMS 2.0” that introduces the CST’s Host Environment Software’s support for the Wind River TMS 2.0 and CPC516SSP switch support package. In Chapter 2 revised the locations of Host Services source files listed in the section “Locations of Host Application Software Components”. Re-wrote part of Chapter 2 to distinguish the procedures for building three software components required of any host application:

• “Building the C-5 Device Driver Library”

• “Building the VxWorks RTOS Image File”

• “Building the Host API Table Services and Queue Services Library”

Table 2 C-Ware Host Application Programming Guide Revision History (continued)



Revision History 21

CST 2.0(Cont.)

9/2001 In Chapter 2 added the new section “Dependencies Among Supplied Drivers and Libraries”. In Chapter 2 removed the section that described building the C-5 Device Driver outside the Tornado Environment. In Chapter 3 revised the location of C language include files that declare Host Services routines in the section “Host Services Interfaces to C-5 Device Driver”. In Chapter 3 revised the pathname of the proxyRpc.c file in the section “Enabling Remote Procedure Call Functionality on the NP”. In Chapter 3 revised the list of Host API Table Services routines and the pathname of the C language include file where they are declared in the section “Host-Side C-Ware API Table Services”.

CST 1.8 6/2001 In Chapter 3 added the new section “Execution Model”. In Chapter 3 updated the set of Host API routines and the lists of host-side C-Ware API Table Services and Kernel Services routines. In the “Enabling Remote Procedure Call Functionality on the NP” topic updated the list of C-Ware API routines that can be invoked on the C-5 from the host processor via a RPC mechanism. Contents of Chapter 6 are substantially new. All dcpMgr class public methods are documented. Removed (obsolete) Chapter 5 “Host Reference Applications”. The ‘hostVPTable’ sample application is no longer included in the C-Ware Software Toolset.

CST 1.7 4/2001 Chapter 1, Chapter 2, and Chapter 3 have been rewritten. Chapter 6 is new for this CST version. In Chapter 1 added the new section “Setting Up Tornado for CDS Host Application Development”. In Chapter 2 added four new sections:

• “Building New Software for the CDS Host Application Module”

• “Building the C-5 Device Driver Library”

• “Loading the Host Application Module”

In Chapter 2 renamed the section “Building New Software for the CDS Host Application Module”. Locations of relevant files have bee updated throughout the document.

CST 1.6 12/2001 In Chapter 5 correct instructions for running the VP Table Host application. Add many new index entries.

Table 2 C-Ware Host Application Programming Guide Revision History (continued)



22 ABOUT THIS GUIDE

Related Product Documentation

Table 3 lists the user and reference documentation for the C-Port silicon, C-Ware Development System, and the C-Ware Software Toolset.

Table 3 C-Port Silicon and CST Documentation Set

DOCUMENT SUBJECT DOCUMENT NAME PURPOSE DOCUMENT ID

Processor Information

C-5 Network Processor Architecture Guide Describes the full architecture of the C-5 network processor.

C5NPARCH-RM

C-5 Network Processor Data Sheet Describes hardware design specifications for the C-5 network processor.

C5NPDATA-DS

C-5e/C-3e Network Processor Architecture Guide

Describes the full architecture of the C-5e and C-3e network processors.

C5EC3EARCH-RM

C-5e Network Processor Data Sheet Describes hardware design specifications for the C-5e network processor.

C5ENPDATA-DS

M-5 Channel Adapter Architecture Guide Describes the full architecture of the M-5 channel adapter.

M5CAARCH-RM

Hardware Development Tools

C-Ware Development System Getting Started Guide

Describes installation of the CDS. CDS20GSG-UG

C-Ware Development System User Guide Describes operation of the CDS. CDS20UG-UG

Software Development Tools

C-Ware Software Toolset Getting Started Guide Describes how to quickly become acquainted with the CST’s software development tools for a given CST platform.

CSTGSGW-UG (Windows)CSTGSGS-UG (Solaris and Linux)

C-Ware Debugger User Guide Describes the GNU-based tool for debugging software running on either the C-Port network processors simulators.

CSTDBGUG-UG

C-Ware Integrated Performance Analyzer User Guide

Describes use of the Integrated Performance Analyzer tool for gathering performance metrics of a C-Port NP-based application running under the simulator.

CSTIPAUG-UG

C-Ware Simulation Environment User Guide Describes how to configure and run a simulation of a C-Port NP-based application using simulator tools.

CSTSIMUG-UG


Related Product Documentation 23

Application Development

C-Ware Application Design and Building Guide Describes tools to build executable programs for the C-Port network processors or simulators and design guidelines and trade-offs for implementing new C-Port NP-based communications applications.

CSTADBG-UG

C-Ware API Reference Guide Describes the subsystems and services that make up the C-Ware Applications Programming Interface (API) for C-Port NP-based communications applications.

CSTAPIREF-UG

C-Ware API Programming Guide Provides practical guidance in programming the C-Ware API services.

CSTAPIPROG-UG

C-Ware Host Application Programming Guide Describes the CST software infrastructure and APIs that support host based communications applications.

CSTHAPG-UG

C-Ware Microcode Programming Guide Describes programming the C-Port network processor’s Serial Data Processors and Fabric Processor.

CSTMCPG-UG

Other Documents

Answers to FAQs About C-Ware Software Toolset Version 2.0

Describes how the directory architecture provided in C-Ware Software Toolset Version 2.0 differs from previous CST releases.

CSTOAFAQ-UG

Table 3 C-Port Silicon and CST Documentation Set (continued)

DOCUMENT SUBJECT DOCUMENT NAME PURPOSE DOCUMENT ID


24 ABOUT THIS GUIDE



CSTHAPG-UG/D

Rev 13
Chapter 1
C-WARE HOST APPLICATION PROGRAMMING OVERVIEW

Introducing C-Ware Host Application Programming

The C-Port C-5, C-5e, or C-3e Network Processor (NP) can be designed into a “system” or “device” (that is, a switch, router, bridge, or other communication equipment system) that includes a host processor. The host processor is typically a fully programmable, general purpose microprocessor. It typically communicates with the NP via a PCI bus interface.

The host application is the software program (or programs) that runs on the host processor and interacts with the programs running on the NP. Host applications extend the usefulness of the NP by allowing you to add functionality beyond the software that runs on the processor itself. Host applications run on a separate processor and interact with programs running on the NP.

Distinguishing Data PlaneFrom Control Plane

Figure 1 on page 26 depicts and distinguishes the two sets of activities that take place on the host processor and on the NP, as follows:

• Data plane tasks — Operations on forwarding path data that occur in real-time. These constitute the communication equipment’s core functions and hence are performance-critical. For example, if the piece of equipment is a switch or router, these operations include receiving, processing, and transmitting packets into and out of the equipment. On such equipment the data plane activities are generally implemented on the NP.

• Control plane tasks — Less time-critical control and management operations that determine general equipment operation. For example, in a switch or router these operations include controlling routing table content, detecting and setting port states, and higher-level management. When designing equipment that incorporates the NP, control plane tasks are often implemented in software running on a distinct and dedicated host processor.

CSTHAPG-UG/D REV 13

26 CHAPTER 1: C-WARE HOST APPLICATION PROGRAMMING OVERVIEW

Figure 1 Distinguishing the Activities Performed on Host Processor and Network Processor

CST Support for HostApplication Development

The C-Ware Software Toolset (CST) provides software development tools, API interfaces, loadable package builders and loader infrastructure, and other software infrastructure to support building both host application programs (and loadable images) and NP application programs (and loadable images). The CST also provides operational NP applications that implement several networking protocols, both under simulation (using the CST’s C-Ware Simulator) and on the appropriate C-Ware Development System hardware.

For more information about developing NP application programs, see the set of CST-related documents listed in “Related Product Documentation” on page 22.

Provided ComponentsFor host application programming the CST also includes a set of Host Environment Software components that include:

• VxWorks kernel and driver — For use with the VxWorks® product from WindRiver® Systems and for use with the Wind River Systems Tornado development environment, the CST includes a pre-built bootable VxWorks kernel image (targeted to the MCP750 board). This image provides a device driver for the C-5/C-5E/C-3E network processor family and a set of basic development tools and infrastructure for developing, loading,

IngressPort

Interface

EgressPort

InterfacePacket/Cell

StreamIngressBit Stream

To Ingress Port Interface

TaggedPackets/Cells

TaggedPackets/Cells Packet/Cell

Stream EgressBit Stream

Data &Control

Data &ControlData

Data &Control

Configuration, Performance,and Error Statistics

Table/RuleUpdates

Classifier QueueingUnit

Host

Modifier

Control

NP

Host


Introducing C-Ware Host Application Programming 27

running, and debugging host application programs and for loading and starting software on the NP under the C-Ware Development System.

(Working with the VxWorks kernel image is described in the C-Ware Development System User Guide document. Building the VxWorks kernel image so that it incorporates the appropriate CST-provided Host Environment Software is described in “Building the VxWorks RTOS Image File” on page 39.)

• Linux Kernel and Driver — The CST includes a pre-built bootable Linux kernel image targeted to the MCP750 board, with a device driver for the C-5/C-5e/C-3e network processor family.

• Host API library — A set of high-level interfaces to support building a host application program. These interfaces utilizes the C-5 Device Driver’s public methods. This component is described in Chapter 3.

• C-5 Device Driver — A C++ class that provides low-level callable interfaces and data interfaces to a C-Port NP. By default, this component is built into the shipped VxWorks and Linux drivers. This component is described in Chapter 6.

• DCP Shell — A command line interface to the Host Environment Software. By default, this component is built into the shipped VxWorks and Linux drivers. The C-Ware Development System User Guide document describes how to use the DCP Shell’s CLI commands.

You can extend the DCP Shell’s set of CLI (command-line interface) commands. The CST provides a tool named dshell that takes a specification file as input and produces C language source code that implements CLI command parsing and operation dispatching. You then link these objects into your VxWorks and Linux driver or into a separate loadable module. This information is found in the section “Implementing Extensions to the DCP Shell Command Set” on page 43.

• Host-based NP diagnostic software — Running the CST’s NP diagnostics is described in the C-Ware Development System User Guide document.

• Host application infrastructure — Other C-Ware host infrastructure tasks spawned from the supplied VxWorks and Linux driver are:

– Console task — Intermediates input/output over the serial port on the C-5 Switch Module (or C-5e Switch Module) board in the C-Ware Development System.



– Host-side C-Ware Debugger agent — Listens on port 32000 to support remote debugging of the C-Ware host application using the C-Ware Debugger running on the development workstation. Debugging NP programs via the CDS’s Host Application Module is described in the C-Ware Debugger Guide document.

– PCI read/write tasks (pci_rd_wr) — Two instances of this task support input/output over the PCI bus connecting the host CPU and the NP.

– Printflistener — Forwards ‘stdout’ output from the C-Ware host application (specifically, C-Ware API ksPrintf() calls) to a “remote terminal” session (via the serial port) or to a telnet session (via the network) running on the development workstation.

– Telnet session listener — Listens on port 32009 for new telnet session requests initiated over the network, spawns one “session context task” per session, then intermediates between each session context task and the remote telnet client.

Support for Static and Dynamic Linkage The CST provides techniques that provide more control and convenience for building your host application or other host-side software infrastructure, as follows:

• Dynamically linked modules — The CST includes support for producing loadable modules that are dynamically linked. For instance, you can use this technique to change whether the software that implements some, even all, the DCP Shell’s CLI commands are linked statically or dynamically into the VxWorks and Linux drivers. You might prefer that some DCP Shell CLI commands be provided as a separate dynamically loadable module (DLM) rather than in the VxWorks and Linux drivers. You use the DCP Shell’s ‘ld’ (load) command to load the module. For more information see the section “Building and Using a Dynamically Linkable Module for the RTOS” on page 48.

• Statically linked modules — The CST offers a convenient makefile technique for statically linking user software with the VxWorks and Linux drivers. Use the USER_OBJECTS makefile variable to direct the make tool to find compiled objects, libraries, or executables. For more information see the section “Building and Using Statically Linking Modules” on page 47.

• User code entry point — The CST supports a preferred entry point for calling user code that is statically linked with the VxWorks and Linux drivers. User code that is


Introducing C-Ware Host Application Programming 29

called directly from the VxWorks and Linux drivers during bootup must define an entry point labeled ‘dcpAppInit’. This is typically a C language function with the signature:

void dcpAppInit(void)

For more information see the section “Preferred Entry Point for Host Application User Code” on page 48.

• CDS Support for Host Application Development

The C-Ware Development System (CDS) is a chassis-based hardware system designed around a mid-plane Compact PCI bus. The CDS can be populated with:

• A (front-plane) Host Application Module, provided in the form of the Freescale MCP750 Single Board Computer and which incorporates the Freescale PowerPC to act as host processor.

• One or more (front-plane) C-5 Switch Modules, which incorporates a C-5 Network Processor and supporting memories

• Some number of (back-plane) Physical Interface Modules (PIMs), each of which carry the required physical interface chips (PHYs) to implement a given network protocol. Each PIM is installed opposite a C-5 Switch Module inside the CDS.

For more information about operating the CDS, see the C-Ware Development System Getting Started Guide document.

For more information about using the CDS in the context of host application program development, see the C-Ware Development System User Guide document.



Host API Programming Versus Device Driver Programming

Host application programs should call the Host API routines to perform required interaction with a NP device. These routines are organized and implemented similarly to the C-Ware APIs used to create NP application programs. These routines utilize the C-5 Device Driver’s public methods.

The Host API routines are intended to promote the portability of applications between the host processor and the NP’s Executive Processor (XP).

It is also possible for your own host application program to utilize the C-5 Device Driver’s public methods by direct invocation.

The C-5 Device Driver (that is, its public and private methods) are intended and offered as a reference implementation of an NP device driver. The host API is a fully-supported backward- and forward-compatible API, but the device driver it uses does not have interface compatibility support.


Host Application Development System Configurations 31

Host Application Development System Configurations

At various stages in the development of your host application, you might find it convenient to use these different system configurations to host application development. Each configuration facilitates a different aspect of host application code development.

Host Environment/Hardware NPDevelopment

This development system configuration uses the C-5 Device Driver running on the CDS’s Host Application Module and a hardware C-Port NP. Host applications are loaded from the application development system workstation at boot time. Because this configuration utilizes a hardware NP, it supports a high level of run-time performance.

Figure 2 illustrates this system configuration.

Figure 2 Host Environment/Hardware C-Port NP Development

C-Ware Development System

Host Application Module (SBC)

C-5 Device Driver

C-5 Switch Module

C-5

PCI

Application Development System(Windows/VxWorks or Linux/embedded Linux)

FTP via Ethernet

Host Application Development



HostEnvironment/Simulated

NP Development

This development system configuration uses the C-5 Device Driver running on the CDS’s Host Application Module and a C-Port NP application running under simulation. The host application is loaded from the application development system workstation at boot time. This configuration provides the NP application with its best interaction with the C-Ware Debugger.

Figure 3 illustrates this configuration.

Figure 3 Host Environment/Simulated NP Development

Because this configuration does not require an actual NP device, it can be used before any user-designed hardware becomes available.

C-Ware Development System

Host Application Module (SBC)

C-5 Device Driver

Application Development System(Windows/VxWorks

or Linux/embedded Linux)

EthernetDriver Redirector PCISRV

C-5Simulator


Host Application Development System Configurations 33

Host EnvironmentSimulation/Simulated NP

Development

This development system configuration operates both the host application and the NP application under simulation.

Freescale does not provide customer support for this configuration.

Figure 4 illustrates this configuration.

Figure 4 Host Environment Simulation/Simulated NP Development

The “Host Sim Sys” and “VxSim or Equivalent” need not be on a separate machine. In most cases those tasks take place on the application development workstation.

Host Simulation System

VXSIM or EquivalentInlcuding C-5 DeviceDriver Functionality

Application Development System(Windows/VxWorks )

EthernetPCISRV

C-5Simulator

DRVRDR



Setting Up Tornado for CDS Host Application Development

The C-Ware Development System (CDS) uses the Freescale MCP750 single board computer (SBC) as its Host Application Module.

Wind River Systems offers documentation of how to set up the Tornado development environment to build software targeted for execution on the MCP750. This documentation is part of your installed Tornado package.

Note that this section applies only to those using VxWorks as the OS on the host. It does not apply to Linux users.

For the Tornado package installed on a Windows 2000/XP workstation, find this documentation at this (default) location:

x:\Tornado\docs\vxworks\bsp\mcp750\PowerPlus.html



CSTHAPG-UG/D

Rev 13
Chapter 2
BUILDING C-WARE HOST APPLICATION PROGRAMS

Building New Software for the CDS Host Application Module

The host application module can be set up under VxWorks or Linux.

VxWorks Note these requirements for building new software for the CDS Host Application Module:

• You have installed the Wind River Systems Tornado environment on your workstation.

On a Windows workstation, if your Tornado product is not installed in the directory C:\tornado\, you must edit the setting of the WIND_BASE variable in the file bin\tornadoCustVars.bat in your CST installation.

• You must possess a Wind River Systems Tornado license for building Freescale MPC750 targets. The C-Ware Host Environment Software was built using Tornado Version 2.0.

The C-Ware Development System’s (CDS’s) Host Application Module utilizes the Freescale MCP750 product, which in turn uses the Freescale PowerPC (PPC) 604 chip.

Freescale ships the Host Application Module with a boot loader already installed in FLASH. To test your software, rebuild the Board Support Package (that is, incorporating your host application) and after re-starting the CDS, download it to the CDS via FTP. (See the C-Ware Development System Getting Started Guide document for more information.)

Follow the Tornado instructions for building Board Support Packages.

To change the C-Port Device Driver or other host-targeted software components, source code is provided.

Linux To develop under Linux a copy of Red Hat Linux 7.2 is required for the server PC. Because Linux is a GPL product no licensing fees are required.

CSTHAPG-UG/D REV 13

36 CHAPTER 2: BUILDING C-WARE HOST APPLICATION PROGRAMS

Locations of Host Application Software Components

Table 4 shows where the various host application software components are located in your CST installation. Each pathname is relative to your CST installation directory.

Dependencies Among Supplied Drivers and Libraries

The CDS Host Environment Software includes:

• C-Port-provided software that contributes to building a new RTOS image for either VxWorks or Linux that is targeted for the CDS’s Host Application Module.

You can build the VxWorks bootable kernel image using the Tornado integrated development environment (IDE) product, in which case you must create and customize a Tornado project for that purpose. Alternatively, you can build VxWorks outside the Tornado IDE environment, as described in “Building the VxWorks RTOS Image File” on page 39.

Linux is built with a normal ‘make’ command. See “Building the Driver and Linux Kernel” on page 41.

To support building host application programs that use the C-Ware Host Environment Software, your build of the kernel file, by default, incorporates the np.a library, described next.

• The np.a library includes:

– C-5 Device Driver, described in Chapter 6.

– Certain Host API routines that are closely related to C-5 Device Driver functionality. The Host API routines are described in Chapter 3.

Table 4 Host Application Development Component Locations

COMPONENT COMPONENT LOCATION (IN CST INSTALLATION)

NP Device Driver drivers\np\src\ npDevC5.c drivers\np\src\ npDevC5.h

Host API drivers\np\usr\hsApi.h

Host Reference Applications apps\hostDmaTest\

Documentation and any modified support files

drivers\doc\


Dependencies Among Supplied Drivers and Libraries 37

Building the np.a library is described in “Building the C-5 Device Driver Library” on page 38.

• The sysSvcsHost.a library that includes Host API Table Services, Host API Queue Services routines, and other routines. You must build this library from components provided in the CST; it is not provided pre-built in the CST. The Host API routines are described in Chapter 3.

Building the sysSvcsHost.a library is described in “Building the Host API Table Services and Queue Services Library” on page 41.

Figure 5 depicts the dependencies of a host application program on the kernel image file and the np.a and sysSvcsHost.a libraries.

Figure 5 Host Application Program Dependencies Upon Host Environment Software Libraries

User’s Host Application Program

RTOS Image

C-5 Device Driver and Certain Host API routines

Host API Table Services and Queue Services

Kernel Image File

np.a Library

sysSvcsHost.a Library

Depends UponDepends Upon

Depends Upon



Related to these dependencies is the following important fact: If you customize the NP Device Driver, you must rebuild both the np.a library and the RTOS image file. In the makefile provided by Freescale there are no explicit dependencies that refer to the components referenced in the np.a library’s makefile.

Building the C-5 Device Driver Library

The following subsections describe how to build the np.a library for VxWorks and for Linux.

VxWorks This section describes how to build the np.a library without using the Tornado development environment on the workstation where you installed the C-Ware Software Toolset (CST).

Depending on where you have installed your CST and Tornado products on your workstation, you must edit the directory paths referenced in the file bin\tornadoCustVars.bat (or bin/tornadoCustVars.sh on Solaris). This is required before performing the steps listed below in this section.

1 In a new DOS command window from the CST’s bin directory run the ‘sv’ command script:

>...\Cst2.4\bin> sv

This command sets the system environment variables for the CST. How to run the ‘sv’ command script is described in the C-Ware Software Toolset Getting Started Guide document.

2 From the CST’s bin directory, execute the ‘tornadoCustVars’ command script:

>...\Cst2.4\bin> tornadoCustVars

This command sets the environment variables used by Tornado.

3 From the CST’s drivers subdirectory, enter this command to build the np.a library:

>...\Cst2.4\drivers> make host_driver


Building the VxWorks RTOS Image File 39

Linux This section describes how to build the np.a library in the Linux environment on the workstation where you installed the C-Ware Software Toolset (CST).

1 From a new shell process on Linux, from the CST’s bin directory, run the ‘sv’ command script.

D:\...\Cst2.4\bin> sv

This command sets the system environment variables for the CST. How to run the ‘sv’ command script is described in the C-Ware Software Toolset Getting Started Guide document.

2 From the CST’s drivers subdirectory, enter the command to build the np.a library:

>...\Cst2.4\drivers> make REV=Linux-mpc750 host_driver

Building the VxWorks RTOS Image File

On the workstation where you installed the C-Ware Software Toolset (CST), when building Board Support Packages (BSPs) for the CDS Host Application Module, perform the following steps to build the VxWorks RTOS image.

This procedure requires that Tornado is already installed on the workstation’s C: drive. The CST can be installed on any drive. The following example assumes that you installed the CST on the workstation’s D: drive.

1 In a new DOS command window, from the CST’s bin subdirectory enter the ‘sv’ command:

D:\...\Cst2.4\bin> sv

This command sets the system environment variables for the CST.

2 To build a VxWorks RTOS image that can link to the C-5 driver library, you must make the following changes to the following files found in this directory:

x:\tornado\target\config\mpc750\

– Makefile — A C-Port-specific section is added to the original Makefile provided by WindRiver to facilitate linking and bootup of the C-5 driver code.

– config.h — The required kernel components are configured. The maximum PCI bus constant is increased to 4. The MPIC configuration data is fixed for a bug in the Tornado version 2.0 release.



– mv2600.h — The MMU CPU_PCI_MEM_SIZE is increased to 64MB.

– pciAutoConfig.h — A bug in Tornado version 2.0 release is fixed.

– sysLib.c — Support for user hardware initialization is added. pciIntLib is included. sysIntEnablePIC() function is enabled.

In your CST installation, a sample of each file listed above is found in this directory:

drivers\doc\

The required changes are indicated in these files by comments containing the text "CPORT CHANGES START" and "CPORT CHANGES END". It is recommended that these files not be directly copied over the originals in your Wind River distribution. Instead, you should manually apply the indicated changes to your Wind River distribution files.

3 In the same DOS command window, from the \tornado\host\x86-win32\bin\ directory set the environment variables used by Tornado by executing the ‘torVars’ command:

C:\tornado\host\x86-win32\bin> torVars

4 From the \tornado\target\config\mpc750\ directory, make a new version of the VxWorks file:

C:\tornado\target\config\mpc750> make clean C:\tornado\target\config\mpc750> make vxWorks

Support for SpecificConsole Baud Rate

Use the provided Makefile to build a VxWorks RTOS image for a user-specified console baud rate. Invoke make as follows:

C:\tornado\target\config\mpc750> make DCP_BAUD_RATE=38400

The name of the kernel produced is vxWorks_baud-rate.

Support for DynamicallyLoadable Modules

In addition, if the VxWorks image must support C-Ware dynamically loadable modules, see the section “Standalone Loader for VxWorks” on page 50.


Building the Driver and Linux Kernel 41

Building the Driver and Linux Kernel

You must set up the build environment for each shell you intend to build under.

The following commands set up the build environment for c5e-b0-hw-debug. Please use the correct configuration for your needs. Refer to the CST documentation for more information if necessary.

cd <CPORT>/bin. sv.sh <CPORT>. configure.sh/c5e-b0-hw-debug

To build the driver you need to issue make in the driver directory as follows:

cd /driversmake REV=Linux-mpc750

This builds the driver and OSAL.

As explained above, a pre-built Linux kernel is available at:

/bin/zImage.prep

To build your own kernel, issue make as follows:

cd /OssTools/linux/linux-2.4.18/binmake REV=Linux-mpc750 kernel

This builds a kernel called zImage.prep in the local directory. The driver and other run time components are automatically incorporated into the kernel during the build process.

Building the Host API Table Services and Queue Services Library

The Host API Table Services and Queue Services are accessed through a library named sysSvcsHost.a. A host application program that requires use of these services must link in this library.

Building the Table andQueue Services Library for

VxWorks

Follow these steps to create this library from the files in your CST installation:

1 In a new DOS command window, from the CST’s bin subdirectory execute the ‘sv’ command:

C:\...\Cst2.4\bin> sv

2 Execute the ‘tornadoCustVars’ command:



C:\...\Cst2.4\bin> tornadoCustVars

3 From the CST’s services subdirectory, execute the ‘make host’ command:

C:\...\Cst2.4\services> make host

After you complete these steps, this library (archive) file is found at this path:

services\lib\host\c5-ppc604-ppcVxworks\sysSvcsHost.a


Implementing Extensions to the DCP Shell Command Set 43

Building the Table andQueue Services Library for

Linux

Follow these steps to create this library from the files in your CST installation:

1 In a new Linux command window, from the CST’s libin subdirectory execute the ‘sv’ command:

>.../Cst2.4/libin> sv

2 From the CST’s services subdirectory, execute the ‘make host’ command:

>.../Cst2.4/services> make REV=Linux-mpc750 host

After you complete these steps, this library (archive) file is found at this path:

services/lib/c5e-Linux-mpc750-debug/sysSvcsHost.a

Implementing Extensions to the DCP Shell Command Set

The DCP Shell is a command-line interface (CLI) to the C-Ware Software Toolset’s (CST) Host Environment Software. As supplied in the CST, the implementation of the DCP Shell is linked into the C-5 Device Driver component (np.a) of the Host Environment Software. In turn, the C-5 Device Driver is linked into a VxWorks or Linux image file that is loadable and bootable on the C-Ware Development System’s (CDS) C-5 Switch Module board or C-5e Switch Module board. When you boot the resulting VxWorks or Linux image, a task is automatically spawned that runs the DCP Shell.

The DCP Shell commands that are provided with the CST are described in the C-Ware Development System User Guide document.

The CST also provides a technique for extending the command set of the DCP Shell. You do so using either of the following implementations:

• (Alternative A) Add command specifications to, or removing command specifications from, DCP Shell’s supplied command set, then build the entire extended set of DCP Shell commands into the C-5 Device Driver.

• (Alternative B) Specify a separate set of command specifications from the default set of DCP Shell commands, then build that set of commands as a C-Ware dynamically linked module (DLM). The DLM is can be loaded and linked into the VxWorks or Linux image at any time after the DCP Shell is running. After the DCP Shell user enters the command to load the DLM that implements the additional shell commands, those commands are available for use.



Implementing AdditionalDCP Shell Commands in

the C-5 Device Driver

To implement Alternative A listed above, you specify the set of DCP Shell commands you wish to implement in your Host Environment Software by performing the following general steps:

1 Specify a set of commands in a command specification file, which contains a series of simple syntax descriptions.

2 From a working directory that you want to contain source code for building the DCP Shell, run the CST’s dshell utility (bin\dshell.exe), which produces a C language source file and a header file that together implement command-line parsing and command dispatching (that is, calls to the appropriate command handler routine) for each command specified in the command specification file. The resulting source file and header file must be made available to the makefile that builds the C-5 Device Driver (np.a) library component of your Host Environment Software.

3 Provide the source files for all command handler routines whose function prototypes are found in the header file produced by dshell utility. These source files must be made available to the makefile that builds the np.a library component of your Host Environment Software.

4 Add code to your host application to call the command table registration function that was generated by the dshell utility. This permits the specified set of DCP Shell commands to be available for use after the DCP Shell is initialized as the VxWorks or Linux image file is loaded and booted.

5 Build the C-5 Device Driver component, which in turn is linked with the CST’s supplied VxWorks or Linux image file to become a new, loadable VxWorks or Linux image file.

The remainder of this section describes:

• The syntax of dshell’s command description language

• DCP Shell’s command handler’s programming model

• Where to find sample code for implementing DCP Shell command specifications

Implementing AdditionalDCP Shell Commands in a

DLM

To implement Alternative B listed above, follow Steps 1 and 2 in section “Implementing Additional DCP Shell Commands in the C-5 Device Driver” on page 44.

Next, follow the instructions for building a DLM given in the section “Building and Using a Dynamically Linkable Module for the RTOS” on page 48.


Implementing Extensions to the DCP Shell Command Set 45

Finally, use the DCP Shell’s ‘ld’ command to load the DLM that implements the additional DCP Shell commands. After the DLM is loaded, the commands are available for use.

Command SpecificationFile Coding

For each command specification file you must provide:

• A name for the command table. This name is referenced when invoking the dshell utility. Specify the table name with a line of code such as this:

%table_name

Where table_name is a series of characters, not including an embedded blank space. For convenience, it is recommended that you use the same name for the table and the file in which it is stored.

• One or more command specifications, expressed in the command specification language described in the next section

• A help block of text, whose first line must be specified as follows:

%help one_or_more_lines_of_text

You can also provide any number of comment lines in the command specification file, with each beginning with the ‘#’ character.

Command SpecificationLanguage

The following line of code demonstrates the syntax of the command specification language:

cmd -abc <-d arg_1> [-e arg_2 -f "arg_3"] arg_4 <arg_5> ["arg_6"] -g;

Where:

• The text of this specification also serves as the “usage text” for the help message that is displayed for this command. Therefore, you should name each command’s arguments to be self-documenting.

• Each non-quoted argument is converted to an integer value; each quoted argument is converted to a string value.

• Angle brackets designate required arguments. Square brackets designate optional arguments.

• ‘cmd’ represents the command name.



• ‘-abc’ and ‘-g’ are examples of a flag argument. Each takes no arguments. Any combination of all the specified letters of all the specified flag arguments (regardless of where they are expressed in the command spec itself ) can be specified and that combination is position-independent. All flag arguments are by definition optional.

• ‘-d arg_1’ is a required, position-independent argument.

• ‘-e arg_2’ and ‘-f ’arg_3’ are optional, position-independent arguments. arg_2 is an integer argument, and arg_3 is a string argument.

• ‘arg_4’ and ‘arg_5’ are required, position-dependent integer arguments.

• ‘arg_6’ is an optional, position-dependent string argument.

The following are syntactically correct invocations of this command:

...cmd -bg -d 23 -a -f debug 45 54 ...cmd -ag 45 54 debug -ag -e 23 // -a, -g flag args expressed as 1 arg

When the user enters these commands at the DCP Shell’s command prompt and using code generated by the dshell utility, the DCP Shell checks the entered command’s syntax, then converts all provided arguments to either integers or strings, then calls the specified command handler routine.

Command HandlerProgramming Model

For each command defined in the command specification file, the dshell utility generates source code that validates user input against each defined command’s specified syntax and that upon syntax validation calls a command handler routine.

Required Parameters Each command handler routine must be defined to have at least two parameters, as follows:

• odesc — (output descriptor) The handler routine passes this argument to a printf()-like, generated function cmdOp() function that produces console output.

• flags — Bitmap that indicates which of certain command-line arguments were specified by the user on the command line. Use this value to test for presence of flag arguments and optional arguments on the user-entered command line. Macros to test for arguments are defined in the header file generated by dshell.


Building and Using Statically Linking Modules 47

The generated source file also implements any additional arguments that are specified in the command specification file. Integer arguments are implemented as ‘int’ types, and string arguments are implemented as ‘char *’ types.

Return Value The command handler routine can return any ‘int’ value, which will be displayed as the result of the command in DCP Shell.

The value ‘CMD_ERR_SYNTAX’ must be returned if an error is found. This causes the DCP Shell to display a syntax error message and the appropriate command help text block, also defined in the command specification file.

Sample Code forImplementing Command

Specifications

See the following files in your CST installation for examples of implementing DCP Shell command specifications:

• Command specification file — drivers/np/usr/npShellTbl.spec

• Command handler routine — drivers/np/usr/npShellCmd.c

• Source code generated by dshell utility — drivers/np/usr/npShellTbl.h

Building and Using Statically Linking Modules

When building the RTOS image file that includes statically linked user code for the host application, ensure that the compiled products (that is, *.o, *.a, or *.out files) are left in this directory in your C-Ware Software Toolset (CST) installation:

• For VxWorks

drivers/lib/c5-ppcVxworks-ppc604-debug/

• For Linux

drivers/lib/c5e-Linux-mpc750-debug/

Two environment variables control the build:

• USER_LIBDIR — Directory where you have placed the user object modules to be statically linked with the kernel.

• USER_OBJECTS — Colon-delimited list of objects to be linked.

You can define and export these variables in the shell or specify them on the make command line.



Preferred Entry Point for Host Application User Code

If you have built your RTOS image file using the C-Ware Software Toolset’s (CST) supplied C-Ware Host Environment Software components, and if you have statically linked your host application code into the supplied C-5 Device Driver (np.a), your host application code will be automatically invoked and booted up as part of booting that RTOS image.

The NP Device Driver provides an entry point for your host application code. That code should supply a function with this signature:

void dcpAppInit(void);

This routine is automatically called by the C-5 Device Driver when its own initialization is complete.

Building and Using a Dynamically Linkable Module for the RTOS

The C-Ware Software Toolset (CST) provides a technique to define and build an executable module that can be loaded and executed, then later unloaded if you wish, after your RTOS image file has loaded and booted on your C-Ware Development System (CDS). In VxWorks use of this technique does not require the Tornado IDE.

After you have built a DLM and after you have booted your CDS by loading and starting an image file, you use DCP Shell commands, ‘ld’ and ‘unld’, to load and unload the module. The DCP Shell command-line interface (CLI) runs in its own task after the CDS has booted and loaded an image file into which has been linked the default components of the C-Ware Host Environment Software.

The DLM feature makes it possible for the host application programmer to develop:

• Host application functionality that can be loaded and unloaded separately from the RTOS

• Ad hoc functionality (debugging utilities, memory mappers, and so on) that can be loaded after the “core” application itself is already resident


Building and Using a Dynamically Linkable Module for the RTOS 49

Location of DLM InterfaceDefinitions

The interface to the DLM functionality is provided in this header file:

drivers/np/os/osDlm.h

This file defines a macro for declaring the load module. In this declaration is found the module’s externally visible name, a pointer to the module’s “init” function, and a pointer to the module’s “de-init” function. The prototypes for the init function and de-init function are also declared in this header file.

The module’s init function is called when the DLM is loaded, and its de-init function is called then the DLM is unloaded.

Coding a DLM You declare a DLM by placing the following line of code in the global scope:

OS_DLM(name, init_function, de-init_function);

The init_function parameter is pointer to a function of the type ‘dcpDlmInit’, and the de-init_function parameter is a pointer to a function of the type ‘dcpDlmDeinit’.

The DLM’s init function must return the value defined as ‘OS_DLM_OK’ on success.

Mechanism of DLMInvocation

Note that after a DLM is loaded, its init function is called from the RTOS task/process/thread that is running the DCP Shell. Thus, the DLM must execute a return to caller in order for control to return to the DCP Shell; otherwise, the user cannot perform the ‘unld’ command to unload the DLM. On the other hand, if the DLM implements code that is intended to remain resident when called from the DCP Shell, the requirement to return to caller does not apply.

If you require the DLM to perform code that must remain resident yet allow control to return to the DCP Shell, you can code the body of the DLM to spawn one or more tasks/processes/threads distinct from the DCP Shell task.

Support by the DCP Shell The DCP Shell offers the ‘ld’ and ‘unld’ commands for loading and unloading a DLM. Their command syntax and operation are as follows:

ld [-n module_name] <file_path> [arg_0] [arg_1] [arg_2] [arg_3]

The ‘ld’ command causes the DLM given by file_path to be loaded by RTOS. The DLM name (as defined in the source code) is derived from the filename part of file_path or can be specified using the ‘-n’ option.



After the DLM is loaded, its defined init function is automatically called and is passed up to four optional command arguments (arg_0, arg_1, arg_2, and arg_3).

Note that all four arguments to the ‘ld’ command are defined as integer values (‘int’) in the CST’s supplied DLM interface header file. The arguments are accepted by the DLM interface’s dcpDlmLoad() routine and the ‘dcpDlmInit’ type (point to function). See the section “Location of DLM Interface Definitions” on page 49.

unld module_name

The ‘unld’ command causes the DLM named module_name to be unloaded from the RTOS. Before the module is unloaded, its defined de-init function is automatically called. There are no arguments passed to the de-init function.

Standalone Loader forVxWorks

If you intend for users of the host application to dynamically load modules on the host processor running the VxWorks RTOS, you must build the VxWorks kernel for the standalone loader. This is accomplished by performing these two steps:

• Defining STANDALONE_LOADER=1 in the environment or in the ‘make’ command line

• Setting -DSTANDALONG_LOADER=1 in ADDED_CFLAGS in the environment or in the ‘make’ command line

For example:

make vxWorks ADDED_CFLAGS=-DSTANDALONG_LOADER=1 STANDALONE_LOADER=1

or, under “sh” shell variants:

$ STANDALONE_LOADER=1 $ ADDED_CFLAGS=”-DSTANDALONG_LOADER=1” $ export STANDALONE_LOADER ADDED_CFLAGS

$ make vxWorks

A standalone loader is not required for Linux.


Loading the Host Application Module 51

Loading the Host Application Module

Now you are ready to make your new image file available for loading into the Host Application Module. This takes place via an FTP download, which is the same procedure as when installing the CDS software for the first time. Consult the VxWorks/Linux documentation for directions about setting up the FTP transfer.

For more information about using FTP to support your first CDS startup, see the C-Ware Development System Getting Started document.

Copy the new image file to the location that your FTP server expects, then simply reboot your CDS chassis.

Note that in the configuration boot parameters file:

• The configuration boot parameters must point to the new image file.

• The parameters must use the user name and password of a valid account for your FTP server.





CSTHAPG-UG/D

Rev 13
Chapter 3
HOST API PROGRAMMING

Overview Host applications can programmatically interact with a C-Port Network Processor (NP) via the Host API routines (which in turn use the C-5 Device Driver component) or can directly invoke C-5 Device Driver public methods. See Chapter 6 for a description of the C-5 Device Driver.

The C-5 Device Driver programming interfaces might not be supported in future releases of the C-Ware Software Toolset and the C-Ware Development System.

This chapter provides a reference description of each Host API function.

The Host API routines can be used with both C-Port NP hardware and the C-Ware Simulator.

Execution Model Use of the C-Ware Host API library depends on a model of program execution that has the following aspects:

• The Host API routines are called from a program that also is built to run under the VxWorks real-time operating system or the Linux operating system. The Host API routines are called from a VxWorks or Linux unit of execution called a “task”.

• Each task that calls the Host API routines can open and work with one and only one NP device for that task’s life span.

• More than one task can work with the same NP device. Successive attempts by separate tasks to “open” or “close” the same NP device are accommodated by the Host API routines. (See hsOpenDcp() and hsCloseDcp().) Tasks that work with the same NP device must use mechanisms not provided in the Host API to synchronize access and use of a given NP device.

• The Host API routines maintain their own internal data structures (independently of the number of calling tasks) that together represent the state of API processing for each open NP device in the overall hardware system.

CSTHAPG-UG/D REV 13

54 CHAPTER 3: HOST API PROGRAMMING

Host Services Interfaces to C-5 Device Driver

The Host API routines provide basic control and access to a C-Port NP device. They allow direct access to the NP’s memory elements and status registers via raw reads and writes over the PCI bus.

Keep in mind the following points when working with the Host API interfaces:

• Read and write calls operate on longword values. All passed parameters must align on the four byte (longword) boundaries of NP Global Bus addresses.

• Read and write calls can pass multiple parameter values, as long as they align on four byte (longword) boundaries.

In your CST installation, see this file for more information about the Host API routines:

services\inc\dcpHostSvcs.h

Two Host API routines, hsCpiInit() and hsCpiFree(), are declared elsewhere:

drivers\np\usr\hsApiCtx.h

The support status of the following Host API functions is “proposed.” See the C-Ware API Reference Guide document for the definitions of API support statuses.


Data Types 55

Data Types cpiMgr

HsDcpHandle

HsProtocolHandle

PKT_BUF_HDR

Description This structure contains relevant information about the context of the Host Services that pertain to a given NP device. Only one instantiation of an object of this type is made for a given NP in the target hardware system. Each task referencing that NP has a pointer to that instantiation.

Type struct

Usage This structure is used by all tasks that reference any C-Port NP device.

Description This is an operating system-neutral handle for a DCP descriptor. A DCP description represents a DCP that is open for access.

Type void*

Usage This identifier is used when opening and closing access to a NP device. NULL is an invalid handle.

Description This is an operating system-neutral handle for a protocol descriptor. A protocol descriptor represents an instance of a C-5 Device Driver ‘pipe’ object between the host processor and a NP device.

Type void*

Usage This identifier is used when opening and closing access to an instance of a ‘pipe’ connection.

Description Not yet documented.

Type struct

Usage Not yet documented.



PKT_DESC

Managing API Global Data Structures

hsCpiFree()

Description Describes a “data” payload buffer and “control” payload buffer pair, as well as the BMU buffer for a DMA operation.

Type struct

Usage The “data” payload is transferred to/from the BMU buffer using DMA, and the “control” payload is transferred to/from the user-defined buffers using programmed I/O.

Description Delete cpiMgr resources.

Signature void hsCpiFree (void);

Arguments (IN) None

Arguments (OUT) None

Returns None

Caveats None

Implementation Notes For more information see “Host API Management of Per-NP Data” on page 81.


Managing API Global Data Structures 57

hsCpiInit()

Description Initialize cpiMgr for a C-Port NP.

Signature int hsCpiInit (char *dcpName);

Arguments (IN) dcpName – Pointer to name of the NP for which cpiMgr initialization is requested.


Returns HS_SUCCESS – cpiMgr successfully created and pointer returned. HS_ERR_MALLOCFAIL – no memory available to create a cpiMgr object. Null pointer returned via ptr. HS_ERR_xxx – error return status from hsOpenDcp() that prevented obtaining dcpMgr object for this NP. Null pointer returned via ptr.

Caveats None

Implementation Notes For more information see “Host API Management of Per-NP Data” on page 81.



Begin/End NP Interaction hsCloseDcp()

hsGetDcpHandle()

Description Close a C-Port NP device that was previously opened via the C-5 Device Driver.

Signature int hsCloseDcp (HsDcpHandle* DcpHandle);

Arguments (IN) DcpHandle – Pointer to a DCP descriptor for a previously opened NP device from a prior call to hsOpenDcp(). This variable is set to NULL after successful execution.

Arguments (OUT) DcpHandle – Pointer to a DCP descriptor for a previously opened NP device from a prior call to hsOpenDcp(). This variable is set to NULL after successful execution.

Returns 0 – Success 1 – Error

Caveats Remember that the input parameter is a pointer, not the value.

Implementation Notes Subsequent attempts to close the same NP device by separate tasks where each has previously opened it, are valid. The Host API run-time component tracks which calling tasks have previously opened a given NP device.

Description Retrieve the handle to an open NP device from the given handle for a named connection (that is, a C-5 Device Driver ‘pipe’) for performing programmed I/O.

Signature HsDcpHandle hsGetDcpHandle (HsProtocolHandle* handle);

Arguments (IN) handle – Pointer to a DCP descriptor.


Returns NULL – Protocol not currently open Otherwise – Valid HsDcpHandle object

Caveats Remember that the input parameter is a pointer, not the value.

Implementation Notes None


Begin/End NP Interaction 59

hsOpenDcp()

Description Open a C-Port NP device via the C-5 Device Driver.

Signature int hsOpenDcp (HsDcpHandle* DcpHandle, const char* name);

Arguments (IN) • DcpHandle – Pointer that is updated to point to the DCP descriptor for the NP to open.

• name – Pointer to a string that represents the “name” associated with the opened NP device, for example, ‘dcp0’, ‘dcp1’.

Arguments (OUT) DcpHandle – Pointer that is updated to point to the DCP descriptor for the NP to open.


Caveats None

Implementation Notes Subsequent attempts to open the same NP device by the same calling task, or by other tasks, are valid. In this case, this routine returns the pointer to the same previously opened NP device.



Host Access to NP Memory

hsReadMemory()

hsSeek()

Description Read the contents of the given C-Port NP memory at a given address into a given buffer in host memory.

Signature int hsReadMemory (HsDcpHandle DcpHandle, unsigned long address, void* buffer, unsigned int count);

Arguments (IN) • DcpHandle – Pointer to a DCP descriptor for a previously opened NP device from a prior call to hsOpenDcp().

• address – Address on the NP device to be read.

• buffer – Pointer to a buffer in host memory that is the target of the read.

• count – Length in bytes of buffer.



Caveats This routine updates the current access pointer for the given NP device. The calling routine must allocate sufficient space in buffer for count bytes to be written.

Implementation Notes Address must align on a Global Bus address longword boundary, and count must be a multiple of four. Data transfer takes place via the host processor’s programmed I/O mechanism.

Description Seek the XP DMEM of an opened C-Port NP device.

Signature int hsSeek (HsDcpHandle DcpHandle, unsigned long address);


• address – Address of the memory to be read.


Returns 0 – Success

Caveats None

Implementation Notes Address must align on a Global Bus address longword boundary.


Host Access to NP Memory 61

hsWriteMemory()

Description Write to the given C-Port NP at a given address from the given buffer in host memory.

Signature int hsWriteMemory (HsDcpHandle DcpHandle, unsigned long address, const void* buffer, unsigned int count);


• address – Address on the NP device to be written.

• buffer – Pointer to a buffer in host memory that is the source of the write.

• count – Length in bytes of buffer.



Caveats This routine updates the current access pointer for the given NP device.

Implementation Notes Address must align on a Global Bus address longword boundary, and count must be a multiple of four.



Programmed I/O Between Host and NP

hsCloseProtocol()

hsFlushProtocol()

Description Close a named connection (that is, a C-5 Device Driver ‘pipe’) for performing programmed I/O from/to the given C-Port NP device.

Signature int hsCloseProtocol (HsProtocolHandle *ProtocolHandle);

Arguments (IN) ProtocolHandle – Pointer to a descriptor for a previously opened C-5 Device Driver ‘pipe’ from a prior call to hsOpenProtocol(). This variable is set to NULL after successful completion.



Caveats None


Description Write any previously buffered contents out the named connection (C-5 Device Driver ‘pipe’).

Signature int hsFlushProtocol (HsProtocolHandle *protocolHandle);

Arguments (IN) protocolHandle – Pointer to a pipe descriptor from a prior call to hsOpenProtocol().



Caveats None



Programmed I/O Between Host and NP 63

hsOpenProtocol()

Description Open a named connection (C-5 Device Driver ‘pipe’) for performing programmed I/O from/to the given C-Port NP device. If already open, return the existing handle.

Signature int hsOpenProtocol (HsProtocolHandle *protocolHandle, HsDcpHandle DcpHandle, int pIndex, int cellSize, int nCells);

Arguments (IN) • protocolHandle – A well known ‘pipe’ discipline.

• DcpHandle – Pointer to a DCP descriptor for a previously opened NP device from a prior call to hsOpenDcp().

• pIndex – Pipe index value, 0 to 7.

• cellSize – Maximum size in bytes of each message.

• nCells – Maximum number of messages in the pipe concurrently.



Caveats None

Implementation Notes Uses existing bindings if possible; otherwise, creates a binding if the number of available C-5 Device Driver ‘pipe’ objects permit.



hsPeekProtocol()

Description Use programmed I/O to read from a named connection (C-5 Device Driver ‘pipe’) to a C-Port NP device. This routine differs from hsReadProtocol() in that the contents that are read are not removed from the pipe and remain available for a subsequent read.

Signature int hsPeekProtocol (HsProtocolHandle protocolHandle, void *buffer, unsigned int count);

Arguments (IN) • protocolHandle – Pointer to a pipe descriptor from a prior call to hsOpenProtocol().

• buffer – Pointer to a user-allocated buffer to hold the results of the read.

• count – Length in bytes of the receiving buffer.



Caveats Calling routine must ensure that the buffer referenced by buffer is of sufficient size to hold the results of the read.



Programmed I/O Between Host and NP 65

hsReadProtocol()

Description Use programmed I/O to read from a named connection (C-5 Device Driver ‘pipe’) to a given C-Port NP device into host memory.

Signature int hsReadProtocol (HsProtocolHandle protocolHandle, void *buffer, unsigned int count, int timeout);


• buffer – Pointer to a user-allocated buffer to hold the results of the read.

• count – Length in bytes to read from the source buffer.

• timeout – Maximum time interval in ticks to wait. Value of ‘-1’ means to wait forever.



Caveats Calling routine must ensure that the buffer referenced by buffer is of sufficient size to hold the results of the read.

Implementation Notes Calling this routine suspends the caller until the given number of bytes have been read.



hsWriteProtocol()

Description Use programmed I/O to write to a named connection (C-5 Device Driver ‘pipe’) to a given C-Port NP device.

Signature int hsWriteProtocol (HsProtocolHandle *protocolHandle, const void *buffer, unsigned int count);


• buffer – Pointer to a user-allocated buffer that is the source of the data to write.

• count – Length in bytes to write from the buffer referenced by buffer.



Caveats None



Model of Operation 67

Model of Operation The model of operation is that for a DMA transfer from the host processor to the NP, the application sets up the “data” and “control” payloads and designates a BMU buffer on the NP. Calling hsPktWrite2() initiates the DMA operation. The NP side code performs a hsPktRead2() operation and receives the “control” payload along with the information about the BMU buffer. The NP side code handles the packet as it sees fit then frees it back to the host processor, at which point the host side can reuse the BMU buffer.

For a DMA transfer from the NP to the host processor, the model is transposed except that the roles of the host side and NP side are reversed.

DMA Data TransferOperations

This set of DMA Data Transfer routines:

• hsPktRead2(), hsPktWrite2()

• hsPktFree2(), hsPktSetBuf2(), hsPktSetBtag2(), hsPktSetDesc2()

are intended to supersede this set of routines:

• hsPktRead(), hsPktWrite()

• hsPktClose(), hsPktOpen()

The first set of routines are implemented to provide a more useful functionality for a broader range of applications. They provide primitives to handle “data” payloads and “control” payloads in a way that reflects real-world usage. The “data” payload is transferred via DMA, and the “control” payload is transferred via programmed I/O.

Mutually Exclusive Sets ofRoutines

This set of DMA Data Transfer services includes two sets of routines that are implemented to be used mutually exclusively, as follows:

• The hsPktRead2() and hsPktWrite2(), routines are intended to supersede the hsPktRead() and hsPktWrite() routines, respectively. Do not mix the use of these two sets of routines in your host application code.

• The hsPktFree2(), hsPktSetBuf2(), hsPktSetBtag2(), and hsPktSetDesc2() routines are intended to be used with the hsPktRead2() and hsPktWrite2() routines in your host application code.



hsPktClose()

hsPktFree2()

Description Close the DMA channel for the designated C-Port NP device.

Signature int hsPktClose (HsDcpHandle handle);

Arguments (IN) handle – Handle to an open NP device.



Caveats None


Description Frees the resources associated with the given packet descriptor (that is, the buffer in the buffer pool on the C-Port NP).

Signature int hsPktFree2 (PKT_DESC* pkt);

Arguments (IN) pkt – Packet descriptor.



Caveats None




hsPktOpen()

hsPktRead()

Description Open the DMA channel for the designated C-Port NP device.

Signature int hsPktOpen (HsDcpHandle handle, int nbuffers, int bufsize);

Arguments (IN) handle – Handle to an open NP device. nbuffers – Number of host processor memory buffers to utilize. bufsize – Size of each host processor memory buffer.



Caveats None


Description Initiate a read DMA data transfer from the host to the designated C-Port NP device.

Signature int hsPktRead (HsDcpHandle handle, DMA_PKTHDR *pktPtr, int timeout);

Arguments (IN) handle – Handle to an open NP device. pktPtr – Pointer to an encapsulating data structure for DMA transfers. See the file dcphca.h. timeout – Maximum time interval in ticks to wait for operation to complete.



Caveats This routine returns only after there is an indication (via a call to dcpMgr::dmaToHostSenseDone()) that the transfer has completed, or when an error detected in the DMA transfer.




hsPktRead2()

hsPktSetBtag2()

Description Receives the packet into the buffers described by the given packet descriptor.

Signature int hsPktRead2 (PKT_DESC* pkt);




Caveats None


Description Sets the buffer pool, tag, and length in the given packet descriptor.

Signature int hsPktSetBtag2 (PKT_DESC* pkt, int pool, int tag, int len);

Arguments (IN) pkt – Packet descriptor. pool – Buffer pool to set. tag – Buffer tag to set. len – Length to set.



Caveats None




hsPktSetBuf2()

hsPktSetDesc2()

Description Sets the buffer header.

Signature int hsPktSetBuf2 (PKT_BUF_HDR* buf, int len);

Arguments (IN) buf – Buffer whose header to set. len – Length to set for the buffer.



Caveats None


Description Sets up the given packet descriptor with the buffer data (“data” and “control”).

Signature int hsPktSetDesc2 (PKT_DESC* pkt, PKT_BUF_HDR* buf, int lenBuf, int lenCtl);

Arguments (IN) pkt – Packet descriptor. buf – Buffer to set. lenBuf – Length of “data” payload buffer to set. lenCtl – Length of “control” payload buffer to set.



Caveats None




hsPktWrite()

hsPktWrite2()

Description Initiate a write DMA data transfer from the host to the designated C-Port NP device.

Signature int hsPktWrite (HsDcpHandle handle, DMA_PKTHDR *pktPtr);

Arguments (IN) handle – Handle to an open NP device. pktPtr – Pointer to an encapsulating data structure for DMA transfers. See the file dcphca.h.



Caveats This routine returns only when there is an indication (via a call to dcpMgr::dmaToDcpSenseDone()) that the transfer has completed, or when an error is detected in the DMA transfer.


Description Transmits the packet from the buffers described by the given packet descriptor.

Signature int hsPktWrite2 (PKT_DESC* pkt);




Caveats None



Miscellaneous 73

Miscellaneous hsClockCalibrate()

hsPackageLoad()

Description Dynamically calibrate the frequency at which the given C-Port NP device is running by reading the cycle counter.

Signature int hsClockCalibrate (HsDcpHandle DcpHandle);



Returns int value of the clock frequency for the given NP device. HS_ERR_BADHANDLE – Error

Caveats None


Description Load a package onto the given C-Port NP device and direct that NP to start executing it.

Signature int hsPackageLoad (HsDcpHandle DcpHandle, void *pkgData, int bootFlags);


• PkgData – Pointer to the caller’s package. This buffer must contain a valid package.

• bootFlags – Length in bytes of the package to be written.

• (Optional) Up to four additional arguments can be passed to this routine; these are passed to the DcpMain() routine on the XPRC at the end of package loading before any NP code executes.



Caveats None




hsPendOnEvent()

hsQueryConfig()

Description Wait for a signal or event from the C-Port NP’s Executive Processor associated with the given DcpHandle.

Signature int hsPendOnEvent (HsDcpHandle DcpHandle, int eventID, int timeout);


• eventID – ID of the event upon which to pend.

• timeout – Maximum time in ticks to wait. Value of ‘-1’ means to wait forever.



Caveats None


Description Obtain the configuration information (driver build time or C-Port NP revision, and so on) for the given NP device.

Signature int hsQueryConfig (HsDcpHandle DcpHandle, QUERY_CONFIG *QueryConfig, const int count);


• QueryConfig – Pointer to the configuration structure to be filled.

• count – Length in bytes of the configuration structure referenced by QueryConfig.


Returns 0 – Success 1 – Error 2 – Device driver’s configuration structure is not the same length as that referenced by QueryConfig.

Caveats None



Miscellaneous 75

hsReset()

hsSignal()

Description Request a warm reset of the given C-Port NP device.

Signature int hsReset (HsDcpHandle DcpHandle);

Arguments (IN) DcpHandle – Pointer to a DCP descriptor for a previously opened NP device from a prior call to hsOpenDcp().



Caveats Reset stops all processing on the NP and no states are preserved.


Description The C-Port NP’s Executive Processor signals an interrupt to the host processor.

Signature int hsSignal (int32 signal);

Arguments (IN) signal –The signal identifier to be notified to the host.


Returns ksStatusSuccess – Success ksStatusResourceError – Error

Caveats None

Implementation Notes The function first checks the HCA (Host Communication Area) in the DMEM24 region to make sure that a previous interrupt is not pending; it then writes the reason for the interrupt (that is, the signal to host memory) using a PCI write and returns ksStatusSuccess. If there is a pending interrupt already, hsSignal() waits for it to clear before posting another one. Then the XP generates a host interrupt causing the host to check its own local memory to find the interrupt to handle rather than polling the XP DMEM. The host then services the interrupt and resets the interrupt pending field (InterruptReasonMask) in the HCA.



hsSymbolImport()

Description Read the value of a symbol exported from the current package.

Signature int hsSymbolImport(HsDcpHandle DcpHandle, char *symbolName, void **pValue);

Arguments (IN) DcpHandle – Handle returned from a prior call to hsOpenDcp(). symbolName – Pointer to symbol name to be imported.pValue – Value of symbol is written here.



Caveats None



Host-Side C-Ware API Table Services 77

Host-Side C-Ware API Table Services

Communications systems use synchronized tables containing topology and control information to make forwarding and characterization decisions. Such tables are accessed in the forwarding path for lookup resolution and forwarding decisions, and are typically managed by an agent that runs on an application processor that adds, removes, and modifies entries in these tables. Examples of such databases would be an IP Routing Table or an ATM Virtual Connection (VC) table.

See the C-5 Network Processor Version D0 Architecture Guide for more information on Table Lookup Unit (TLU) functionality. See also the Table Services chapter in the C-Ware API Programming Guide for more information.

See the C-Ware API Programming Guide for information about using these functions in NP XPRC and CPRC programs and host application programs.

The host-side C-Ware API Table Services that are currently implemented include:

• tsTableInitialize — Initialize Table Services.

• tsTableInit() — Initializes a Table Services table structure.

• tsTableCreate() — Creates a table in memory using the tableID returned from tstableInit().

• tsEntryInsert() — Insert an entry into a table in memory.

• tsEntryDelete() — Delete a table entry.

• tsEntryFindNext() — Find the next non-empty entry in a table.

• tsEntryLookup() — Look up an item in a table.

• tsEntryModify() — Modify an entry in a table.

In your CST installation the Host API Table Services routines are defined in this file:

services\inc\dcpTableSvcs.h



Supported Table Types andOperations

Table 5 shows the Table Services operations that are supported on the C-5 Network Processor under the on-chip API, Host API, and offline API (via the OLTBL library and technique).

Table 5 Table Services Operations Supported for the C-5 On-chip, Host, and Offline APIs

TABLE TYPE ON-CHIP (XP) API

ON-CHIP (CP) API

HOST API (ONE C-5) OFFLINE API

Data C, D, I, L, M I, L, M C, D, I, L, M C, D, I, L, M

Vp-Trie/Data L, M L, M C, D, F, I, L, M C, D, F, I, L, M

Index8/Vp-Trie/Data L, M L, M C, D, F, I, L, M C, D, F, I, L, M

Index16/Vp-Trie/Data L, M L, M C, D, F, I, L, M C, D, F, I, L, M

Hash/Trie/Key C, D, F, I, L, M L, M C, D, F, I, L, M C, D, F, I, L, M

Index/Trie/key None None None None

Hash None None None None

Trie None None None None

Key None None None None

Legend:C = createD = delete entry F = find next non-empty entry I = insert entry L = lookup (find-read)M = modify


Host-Side C-Ware API Table Services 79

Table 6 shows the Table Services operations that are supported on the C-5e and C-3e Network Processors under the on-chip API, Host API, and offline API (via the OLTBL library and technique).

Table 6 Table Services Operations Supported for the C-5e & C-3e On-chip, Host, and Offline APIs

TABLE TYPE ON-CHIP (XP) API

ON-CHIP (CP) API

HOST API (ONE C-5E/C-3E) OFFLINE API

Data C, D, I, L, M I, L, M C, D, I, L, M C, D, I, L, M

LPM L, M L, M C, D, F, I, L, M C, D, F, I, L, M

Hash/Trie/Key C, D, F, I, L, M L, M C, D, F, I, L, M C, D, F, I, L, M

Index/Trie/key None None None None

External None None None None

Hash None None None None

Trie None None None None

Key None None None None

Legend:C = createD = delete entry F = find next non-empty entry I = insert entry L = lookup (find-read)M = modify



Enabling Remote Procedure Call Functionality on the NP

The following Host API routine is implemented to be invoked as a remote procedure call (RPC) on the C-Port NP:

• ksEventSet()

To enable the NP application to receive Host API RPC requests, the user must modify the following source file and include it when rebuilding the NP application’s XPRC program:

services\kernel\chip\np\xprc\src\proxyRpc.c

In this file find this block of code:

#ifdef HOST_TEST #define RPC_ENABLE 1 #else #define RPC_ENABLE 0 #endif

In this code block change the line:

#define RPC_ENABLE 0

to this:

#define RPC_ENABLE 1

Making this change pertains only to a NP application that is intended to respond to RPC-based Host API calls in the host application program. This change allows a response to such calls for NP applications other than those supporting the Wind River Systems’ Tornado for Managed Switches (TMS) Version 2.0 product.


Host-Side C-Ware API Kernel Services 81

Host-Side C-Ware API Kernel Services

See the C-Ware API Programming Guide and the C-Ware API Reference Guide for information about using these functions in programs.

The host-side C-Ware API Kernel Services that are currently implemented include:

• ksMdioRead() — Initiate a high speed serial bus read request.

• ksMdioReadComplete() — Check to see if a pending MDIO operation has completed, and if it has, return the data.

• ksMdioWrite() — Initiate a high speed serial bus write request.

• ksMdioWriteComplete() — Check to see if a pending MDIO write operation has completed.

In your CST installation these routines are defined in the include file:

services\inc\dcpKernelSvcs.h

Host API Management of Per-NP Data

The Host API routines use a set of API-global data structures that represent the context of the host processor’s programming interaction with each C-Port NP device in the overall system.

In much the same way as the C-5 Device Driver layer dedicates a dcpMgr object to each NP device in the overall system, the Host API dedicates a cpiMgr data structure for management of the API’s own context for each NP in the overall system.

The cpiMgr structure has this definition:

typedef struct cpiMgr_tag {HsDcpHandle dcpObj;int32u serviceInit;SEM_ID sem;TsSavedData _tsSavedData;MsgData localRxResp_data[8];char dcp_name[10];

} cpiMgr;

As additional per-NP data is defined in future CST releases, additional members will be added to the cpiMgr structure.



Two Host API routines perform the work to manage these API-global data structures:

int hsCpiInit(char *dcpName);void hsCpiFree();

In your CST installation these two routines are defined in the file:

drivers\np\ppcVxworks\src\hsCpiMgr.cpp

Calling hsCpiInit() allocates a cpiMgr structure and, if no other task has previously called hsCpiInit(), initializes that structure’s members, as follows:

• Sets the dcpObj member to the dcpMgr pointer for the named NP.

• Initializes a pointer to this structure and stores it in the Host API-global variable cpiObj.

hsCpiInit() returns a value based on the enumerated list of HS_* return values found in dcpHostSvcs.h. The routine also maintains a count of the number of tasks that reference the NP device and that use the cpiMgr object.

The hsCpiFree() routine, called by a task referencing the NP, decrements the count of the number of tasks that reference this NP and that use this cpiMgr object. If this count goes to zero, hsCpiFree() frees the heap storage allocated for the cpiMgr structure.

Using hsCpiInit() and hsCpiFree()When spawned, each user task must call hsCpiInit() and pass to it a pointer to the NP name string as a parameter. After hsCpiInit() returns successfully, an initialized cpiMgr structure exists and the task has its own private pointer to the structure.

User code is also required to call hsCpiFree() before exiting a task, so that heap space for the cpiMgr structure can be freed when there are no longer any tasks using the structure referencing this NP.



CSTHAPG-UG/D

Rev 13
Chapter 4
PROGRAMMING THE M-5 CHANNEL ADAPTER

Overview The M-5 Channel Adapter requires software configuration before it can process payload data. The application code’s initialization section makes calls to an M-5 API library to accomplish this. There are also calls in the M-5 API to read and set other state such as error condition counts and other statistics.

The M-5 Services are defined in:

dcpM5.h

The M-5 API Library The C-Ware CST 2.4 release of the M-5 API library is available only in the host environment. When an application is run, the host-resident portion of the application makes calls to the M-5 API library to establish host communication with the M-5 over the Slow Speed Interface and to configure it according to the application’s requirements. Once the application is running and processing data, the host portion of the application can continue to make calls to the M-5 API library to examine and modify internal M-5 state.

The M-5 API library is organized into several groups of routines:

1 Routines to establish a connection to a particular M-5, synthesize a ’handle’ for subsequent access to it, and to perform the most basic initialization steps.

2 Routines at the lowest level to read and/or write individual bytes in the M-5’s internal address space. These routines are intended to be used only by applications that have extraordinary and unique M-5 configuration requirements. Freescale cannot ensure that application calls to these low level routines will work compatibly with the higher level routines in the M-5 API library. These low-level routines are documented in the file \drivers\np\usr\hsApi.h.

3 Routines to configure one data channel at a time. These routines can be used to configure one of the M-5’s 48 channels for a particular data rate, physical channel number, and other parameterized characteristics.

CSTHAPG-UG/D REV 13

84 CHAPTER 4: PROGRAMMING THE M-5 CHANNEL ADAPTER

4 Routines to configure the entire M-5 chip to a particular commonly used configuration, such as 48 x OC-1, 12 x OC-3, etc. The advantage to using these routines over the routines in the previous group is that these routines will automatically and correctly configure other associated states, such as the Flow Schedule Table.

5 Routines to read/write error and statistics registers.

Initialization m5Init()

m5Open()

Description This function establishes communication with the M-5, clears error counters, and disables all channels.

Signature M5ErrorCode m5Init(M5Desc* m5desc, M5PortMode portMode);

Arguments (IN) • m5Desc – Handle to the M-5.

• portMode – M-5 Port Mode (front port or back port).


Returns M5ErrorCode according to initialization status.

Caveats None


Description This function gets a handle to specific M-5 associated with a specific NP.

Signature M5ErrorCode m5Open(HsNpDesc np, uint16 addr, M5Desc* m5Desc);

Arguments (IN) • np – Handle to the NP.

• addr – Address of the M-5 on the lssi bus.

Arguments (OUT) • M5Desc – The returned handle to the M-5

Returns M5ErrorCode according to configuration status.

Caveats None



The M-5 API Library 85

Configuration m5ChannelConfigOc1()

Description This function configures one specific OC-1 channel according to specifications.

Signature M5ErrorCode m5ChannelConfigOc1(M5Desc* m5desc, M5ChannelId channel, CpId cp, IndexId index, M5ChannelRateControl rateControl, uint16 addToFirstChunk, M5ChannelMode mode, uint16 minPacketSize);


• channel – PHY channel.

• cp – CP that will process the channel.

• index – Index on the CP (0,1, or2).

• rateControl – Enable packet transfer rate control.

• addToFirstChunk – First chunk additional bytes.

• mode – M-5 Channel Mode (cell or packet).

• minPacketSize – Minimum effective packet size



Caveats Calling this function causes the entire flow schedule table to be rewritten. If you require a nonstandard configuration of the flow schedule table, write it by calling m5SetFlowSchedTable() after calling m5ChannelConfigOc1().




m5ChannelConfigOc1x48()

Description This function configures the M-5 as 48xOC-1, using default Cluster/CP/Index and FIFO mappings.

Signature M5ErrorCode m5ChannelConfigOc1x48(M5Desc* m5desc, M5ChannelRateControl rateControl, uint16 addToFirstChunk, M5ChannelMode mode, uint16 minPacketSize);


• rateControl – Enable packet transfer rate control.



• minPacketSize – Minimum effective packet size



Caveats Calling this function causes the entire flow schedule table to be rewritten. If you require a nonstandard configuration of the flow schedule table, write it by calling m5SetFlowSchedTable() after calling m5ChannelConfigOc1x48().




m5ChannelConfigOc3c()

m5ChannelConfigOc3cx16()

Description This function configures one specific OC-3c channel according to specifications.

Signature M5ErrorCode m5ChannelConfigOc3c(M5Desc* m5desc, M5ChannelId channel, CpId cp, uint16 addToFirstChunk, M5ChannelMode mode);



• cp – CP that will process the channel.





Caveats Calling this function causes the entire flow schedule table to be rewritten. If you require a nonstandard configuration of the flow schedule table, write it by calling m5SetFlowSchedTable() after calling m5ChannelConfigOc3c().


Description This function configures the M-5 as 16xOC-3c, using default Cluster/CP/Index and FIFO mappings.

Signature M5ErrorCode m5ChannelConfigOc3cx16(M5Desc* m5desc, uint16 addToFirstChunk, M5ChannelMode mode);






Caveats Calling this function causes the entire flow schedule table to be rewritten. If you require a nonstandard configuration of the flow schedule table, write it by calling m5SetFlowSchedTable() after calling m5ChannelConfigOc3cx16().





m5ChannelConfigOc12cx4()

Description This function configures one specific OC-12c channel according to specifications.

Signature M5ErrorCode m5ChannelConfigOc12c(M5Desc m5Desc, M5ChannelId channel, ClusterId cluster, M5ChannelMode mode);



• cluster – Cluster that will process the channel.






Description This function configures the M-5 as 4xOC-12c, using default Cluster/CP/Index and FIFO mappings.

Signature M5ErrorCode m5ChannelConfigOc12cx4(M5Desc* m5desc, M5ChannelMode mode);





Caveats Calling this function causes the entire flow schedule table to be rewritten. If you require a nonstandard configuration of the flow schedule table, write it by calling m5SetFlowSchedTable() after calling m5ChannelConfigOc12cx4().





m5CheckFlowSchedTable()

Description This function configures the M5 as one OC-48c channel according to specifications.

Signature M5ErrorCode m5ChannelConfigOc48c(M5Desc* m5desc, M5ChannelMode mode);







Description This function examines the Flow Schedule Table for consistency (that is, makes sure that no channels are oversubscribed or undersubscribed).

Signature M5ErrorCode m5CheckFlowSchedTable(M5Desc m5Desc);




Caveats Currently, this function only ensures that each channel appears the appropriate number of times in the flow schedule table. It does not ensure that the entries for a given channel are properly spaced in the table.




m5SetFlowScheduleTable()

Traffic Management m5ChannelDisable()

Description This function sets all of the flow schedule table registers according to specifications.

Signature M5ErrorCode m5SetFlowSchedTable(M5Desc* m5desc, M5FlowSchedTable* table);


• table – Flow schedule table.



Caveats This method does not check whether the flow schedule table is configured correctly. It should be called with extreme caution.


Description This function disables a channel in the ingress channel.

Signature M5ErrorCode m5ChannelDisable(M5Desc* m5desc, M5ChannelId channel);


• channel – The channel to disable.



Caveats None




m5ChannelEnable()

m5ChannelFifo()

Description This function enables the ingress path of the specified PHY channel.

Signature M5ErrorCode m5ChannelEnable(M5Desc* m5desc, M5ChannelId channel);


• channel – The channel to enable.



Caveats None


Description This function queries the current configuration for the (GMII, Fifo) tuple used by a specified PHY channel.

Signature M5ErrorCode m5ChannelFifo(M5Desc* m5desc, M5ChannelId channel, M5GMIINo* gmii, M5FifoNo* fifo);



Arguments (OUT) • gmii – The returned gmii number.

• fifo – The returned fifo number.


Caveats None




m5FifoChannel()

m5GetStatus()

Description This function queries the current configuration for the channel using the specified (GMII, Fifo) tuple.

Signature M5ErrorCode m5FifoChannel(M5Desc* m5desc, M5GMIINo gmii, M5FifoNo fifo, M5ChannelId* channel);


• gmii – The gmii number.

• fifo – The fifo number.

Arguments (OUT) channel – The returned PHY channel.


Caveats None


Description This function queries the M-5 status registers.

Signature M5ErrorCode m5GetStatus(M5Desc* m5desc, M5Status* status);

Arguments (IN) m5Desc – Handle to the M-5.

Arguments (OUT) status – Returned status.

Returns M5ErrorCode according to status of operation.

Caveats None




m5SetEgressSequenceNo()

m5SetMpsnTimeout()

Description This function sets the next expected M5 egress sequence number.

Signature M5ErrorCode m5SetEgressSequenceNo(M5Desc* m5desc, uint16 seqNo);


• seqNo – Sequence number.



Caveats None


Description This function sets the M5 missing packet timeout value.

Signature M5ErrorCode m5SetMpsnTimeout(M5Desc* m5desc, M5MpsnTimeout timeout);


• timeout – Timeout value.



Caveats None




M-5 Programming Examples

The following code examples illustrate the use of the M-5 API.

Example 1: Configuring theM-5 as an Oc-48c channel

in Front Port mode

This example illustrates obtaining a handle to an M-5 device and configuring the device as a single Oc-48c channel in front port mode.

HsNpDesc np;int addr; M5Desc m5Desc;M5ErrorCode err;

/* Assume the following: * - np has been assigned a valid np handle via a call to hsOpen() * - addr has been assigned the correct address of the M-5 device * on the lssi bus of that NP */

/* Get a handle to the M-5 */err = m5Open(np, addr, &m5Desc); /* Initialize the M-5 */err = m5Init(m5Desc, FrontPort);

/* Configure the M-5 as an Oc-48c */err = m5ChannelConfigOc48c(m5Desc, FrontPort);

Example 2: ConfiguringIndividual M-5 Channels

This example illustrates configuring several individual channels on the M-5. The example configures 3 Oc-1 channels processed by CP0, 3 Oc-3c channels processed by CP1, CP2, and CP3, and 3 Oc-12c channels processed by clusters 1, 2, and 3.

M5Desc m5Desc;M5ErrorCode err;

/* Assume that m5Desc has been assigned a valid M-5 handle via a call* to m5Open() */ /* Initialize the M-5; this will clear all error counters and disable * any channels that were already configured and enabled */err = m5Init(m5Desc, FrontPort);


M-5 Programming Examples 95

/* Configure channels 0, 1, and 2 as Oc-1 channels */err = m5ChannelConfigOc1(m5Desc, 0, 0, Index0, 0, 0, PacketMode, 0);err = m5ChannelConfigOc1(m5Desc, 1, 0, Index1, 0, 0, PacketMode, 0);err = m5ChannelConfigOc1(m5Desc, 2, 0, Index2, 0, 0, PacketMode, 0); /* Configure channels 3, 4, and 5 as Oc-3c channels */err = m5ChannelConfigOc3c(m5Desc, 3, 1, 0, PacketMode);err = m5ChannelConfigOc3c(m5Desc, 4, 2, 0, PacketMode);err = m5ChannelConfigOc3c(m5Desc, 5, 3, 0, PacketMode); /* Configure channels 6, 7, and 8 as Oc-12c channels */err = m5ChannelConfigOc12c(m5Desc, 6, Cluster1, PacketMode);err = m5ChannelConfigOc12c(m5Desc, 7, Cluster2, PacketMode);err = m5ChannelConfigOc12c(m5Desc, 8, Cluster3, PacketMode);

M-5 Test Program A simple host program to demonstrate some of the functionality of the M-5 API is provided inthe following location

\services\m5\host\np\src\m5Test.c





CSTHAPG-UG/D

Rev 13
Chapter 5
PROGRAMMING THE DEVICE DRIVER

Overview This CST release supports a device driver architecture that is operating system (OS) independent and adaptable to many programming environments, including VxWorks and Linux.

Porting layers can be implemented for the driver framework to make it work on a variety of operating systems. The CST provides and supports porting layers for two target operating systems - VxWorks and Linux. Information specific to each of these platforms is provided in the corresponding sections

Organization This chapter contains the following sections:

• “Device Driver Design” provides an overview of the device driver development framework.

• “Porting and Configuration” provides information on porting and configuring the device driver on various operating systems.

• “Device Driver API” provides a reference for the device driver application programming interface.

• “The Portable Device Driver” provides step-by-step instructions for building the device driver in a Linux environment.

CSTHAPG-UG/D REV 13

98 CHAPTER 5: PROGRAMMING THE DEVICE DRIVER

Device Driver Design The NP Device Driver Development framework consists of code organized into well-defined layers and objects. The framework makes it convenient to develop device drivers in a structured way. The commonly used mechanisms and abstractions in device drivers are abstracted into well-defined services that can be reused in any driver that needs them. The drivers themselves must conform to object interface specifications so that they may be integrated into the overall driver framework. This section describes the design of the C-Ware Driver Development Kit (DDK).

Organization The section is organized as follows.

1 First the overall model of the framework is presented. The various objects and layers are identified along with their associated behavior. The general workings of the model are explained in terms of the interactions of these objects and layers.

2 Each object and layer is described in detail. The design description is broken down into behavior / functionality and the interface. Pointers to the actual code are included.

High Level Model Figure 6 depicts the high level model of the DDK framework. The major objects and layers are shown. These objects and layers are described in detail in subsequent sections.


Device Driver Design 99

Figure 6 High Level Model

Porting LayersOne of the primary objectives for the design is portability. A few design patterns are used to accomplish this goal.

The services expected from the operating system are abstracted into primitives contained in the Operating System Abstraction Layer (OSAL). The rest of the code is written using the semantics of these primitives. The code will run on a system where these primitives are provided. U-OSAL represents the user space OSAL and K-OSAL represents the kernel space OSAL. The layer contains the common OS primitives for tasking, semaphores, timers, queues etc. The code for OSAL is located at services\osal

The kernel-space / user-space device interface is abstracted into the “U-OSAL Device Interface”. This layer contains primitives to handle devices from the user-space; for example, primitives to open, close, and issue commands to a device. Higher level libraries are written using the primitives in this layer. The libraries may be ported to any system

DeviceUI

DI

BusUI

EP EP EP

Kernel Porting Layer

U-OSAL (Device Interface)

Host Services API

DeviceUI

DI

DeviceUI

DI

BusUI

BusUI

U-O

SA

LK

-OS

AL

KernelBoundary

Hardware



where this layer is implemented for the required semantics. The interface is located in services\osal\inc\osDev.h.

The purpose of the Kernel Space Porting Layer is to map the kernel environment of an OS to the object interfaces in the driver model. The kernel environment mainly deals directly with the device object. Please note that the user-space / kernel-space separation is not mandatory and applies only to operating systems that require it. It is possible to map the user-space device interface directly to the objects in the driver model and bypass the “Kernel Space Porting Layer” entirely.

ObjectsThe two major classes of objects in the driver model are device objects and bus objects.

• Device objects are instantiated one per physical device and bus objects one per physical bus.

The device objects control the associated device and implement commands that the user can invoke to interact with the device. They also implement interrupt service routines and deferred processing routines to handle the interrupts that may be delivered to the device object.

• Bus objects control the physical bus. They implement primitives that allow the user to send data on the bus.

Each of these objects may have multiple users of its service. Each user is associated with the objects via an end-point (EP). The object creates an end-point for the user, populates it with the relevant context, and passes a handle for it to the user. The user presents this handle with each service request and the object fulfils the request based on the context it accesses via the handle.

• Figure 6 explicitly depicts some objects labeled end points (EP). As stated earlier, all objects implement a notion of end points that serve as service access points. The EPs at the device object boundary happen to be a bit more sophisticated than the EPs supported by other objects and serve as the service access points for the end user. That is why they are called out especially in the diagram.

System InstantiationThe system instantiation starts with the initialization of the bus objects. The bus objects enumerate the bus they control. They create a device object for each physical device that is found and connect the appropriate interrupt line to it. After all the buses are initialized



the system contains a device object for all the devices it is connected to. At this point the system is ready for users to start opening devices and interacting with them.

Buffer Management and IPCThe driver framework implements a standard buffer management and inter-processor communication mechanism for devices that want to use it. The data structure “NpCmd” for a command buffer is located in the file drivers\np\src\npDevShare.h.

The buffer management and IPC mechanisms are general driver-level utility facilities that are available to the implementers of device drivers within this framework. They may be used whenever buffers, queuing, or IPC between the host and the device are required. The C-5 device driver makes extensive use of these facilities and uses them to implement the abstraction of ports. The higher level facilities such as RPC are built on top of these primitive mechanisms.

A socket is an abstraction that allows inter-processor communication by an exchange of command buffers. A socket comprises a set of buffers, a transmit connection, and a receive connection. A connection also includes a producer queue and a consumer queue. The model is that a transmitting entity allocates buffers from the socket and then transmits them. The buffers are allocated from the transmit connection’s producer queue and are queued into the transmit connection’s consumer queue. The receiving entity gets the buffers off the consumer queue and frees them back to the producer queue. The roles of entities are reversed for buffers flowing in the other direction. The code for buffer management using sockets is located in drivers\np\src\npSock.h and drivers\np\src\npSock.c.

A port is an abstraction for an end-point where the users of sockets access its services. Ports are bound to sockets and have a unique identifier. The sockets can multiplex buffers originating from many ports on the same socket. The buffers are de-multiplexed based on port identifiers and delivered to the right port at the other end.



Figure 7 IPC Framework

Interrupt HandlingThe driver framework uses the interrupt mechanisms provided by the OSAL. The mapping of the OSAL interrupts to the physical interrupts depends on the implementation of OSAL for that platform. The driver framework depends on the semantics of the OSAL primitives to ensure that once an interrupt service routine (ISR) is connected to an OSAL interrupt it will be dispatched when that interrupt occurs.

The device objects supply the ISR and deferred processing routine (DPR) routines. The driver framework arranges for the ISR routine to be dispatched if an interrupt occurs for that device.

Interrupts are handled in two stages. When the ISR is first dispatched it is expected to do minimal processing at the interrupt level. This may include setting up a command buffer and clearing the interrupt. The ISR may return a non-NULL value. If it does then its associated DPR will be dispatched with the return value from the ISR as its argument. The DPR is executed in a non-ISR context and is free to invoke most any OSAL service.

Please note that the ISR / DPR model is not mandatory. A device object can decide for itself its interrupt handling strategy. All it has to do is to return a NULL value from the ISR and the DPR will not be dispatched.

Low Level Model Object ModelThe various objects in the model implement a common design pattern. A class of objects like “device” or “bus” implements a standard interface. This interface takes the form of a set of pointers to functions. An instance of a class populates the data structure with

Socket

TxConnection

Producer

RxConnection

Consumer

Producer

Consumer

Socket

TxConnection

RxConnection

Queues

PortsPorts



pointers to its own methods. A user invokes the services of the object by using these pointers. This allows the users to invoke the services of all the instances of that class in a standard way while allowing the various instances to implement different functionality.

The objects also implement the notion of an end-point. An object can have multiple users bound to it. It maintains the context for each user in a data structure referred to as an end-point. To invoke the services offered by an object, a user first creates an end-point. The object returns a handle for the end-point and the user uses the handle in each call made into the object.

The various objects are implemented in a object oriented framework. The object oriented notions of methods, base class, virtual functions and inheritance are emulated in the C programming language (instead of using C++ directly, because of architectural considerations).

In most cases the user does not invoke the services of an object directly by dereferencing the pointers in the interface. Instead, a set of functions that represent the class interface do that by accepting the end-point handle, accessing the object pointer stored in the end-point, and then invoking the relevant method through the pointer.

The objects also implement inheritance to a certain degree. The base class is represented by a data structure. A class may be derived from it by defining a data structure with additional fields while including the base class data structure as the first element. This allows for class common data structures, methods, and functionality to be abstracted. The class common functionality only deals with the class common data structure. The derived class-specific functionality deals with the derived class-specific data structure. The methods are always passed as a pointer to the base object - which serves as the "this" pointer. The base class-specific methods operate on the base class specific data accessed via "this" pointer. The derived class methods deal with the corresponding derived class data accessed via "this" pointer.



Figure 8 Object Model

A typical call into an object has the syntax:

function(handle, argument, …)

The base class implementation of function has access to the base class data structure. It may call the appropriate interface function, passing the object as an argument. The interface function typecasts the object to the derived class data structure and thus has access to the additional fields.

Device ObjectThe class definition of the device object is located in drivers\np\sr\npDevPriv.h.

The class user interface for the device object is located in drivers\np\src\npDev.h.

The device object offers a simple interface to its users. It offers primitives to create an end-point and interact with the device by issuing commands to the device. The end-point object has a queue in it, which is used to hold command buffers that arrive asynchronously.

The device object also implements an interface that is used by the driver framework. This interface primarily consists of the ISR and DPR. There are additional methods to manage the creation and deletion of device objects. Figure 9 depicts the device object interface.



Figure 9 Device Object Interface

Bus ObjectThe class definition of the Bus object is located in drivers\np\src\npBusPriv.h.

The class user interface is located in drivers\np\src\npBus.h.

The Bus object offers a simple user interface to transmit data of different sizes on the bus. It also offers a management interface used by the driver framework to create and delete Bus objects. Figure 10 depicts the Bus object interface.

DevOpen

DevClose

DPR

ISR

Cmd

EpClose

EpOpen

DevAlloc

EP

EventQueue



Figure 10 Bus Object Interface

The Bus object maintains the address of the device in the end-point that it creates for it. The structure of this address depends on the particular bus that the object controls. For the PCI bus the object maintains the base address for memory accesses and PCI bus-device-function tuple for configuration accesses. The user of the bus object need only supply the offset of the data element into the device address space for the access.

The Bus object enumerates the bus in its open method. It creates device objects for all the devices found on the bus and connects them to the appropriate ISR. The bus object creates a device object for all the devices it recognizes on the bus and determines the interrupt vector for that device. It passes in the OSAL identifier for this interrupt vector into the initialization function of the device object. During the device object initialization the interrupt vector is installed along with the pointer to the device using the OSAL ISR handling primitives. Eventually when the interrupt occurs, the OSAL interrupt handling framework calls the ISR for the device by calling the corresponding method in the method set for the device.

Driver ObjectThe driver object is the container object for all of the other objects. It is responsible for the management of the driver framework as a whole. The class definition of the driver object is located in drivers/np/src/npDrvPriv.h. The user interface is located in drivers/np/src/npDrv.h.

BusOpen

BusClose

Write8

Cmd

EpClose

EpOpen

Write32

Write16

EP

Addr



Object Instances This section discusses some of the instances of the object classes described earlier.

File Naming ConventionThe prefix “npDev” or “npBus” states the class of which the specific object is an instance.

The suffix “Priv” indicates that the contained code is for the consumption of the class itself or its friend objects.

The suffix “Share” indicates that the contained types are shared with the code running on the device or some other entity.

PCI Bus ObjectThe implementation of the PCI Bus object is very specific to the OS that the driver framework is ported to. It uses the native OS primitives to access the PCI bus. The implementation of this object is found in the OS-specific part of the driver framework.

The implementation for VxWorks is located in drivers\np\os\ppcVxworks\osBusPci.c.

The implementation for Linux is located in drivers\np\os\Linux\osBusPci.c.

C-5 Device ObjectThe implementation of the C-5 device object is located in:

drivers\np\src\npDevC5.c

drivers\np\src\npDevC5.h

drivers\np\src\npDevC5Priv.h

drivers\np\src\npDevC5Share.h

The implementation uses several kinds of sockets. It uses a separate one for DMA, printf traffic, gdb, and all other command traffic. All the commands implemented are located in the file mentioned above.

The C-5 device object implementation uses the socket mechanism exclusively for IPC. The interrupt arguments are also delivered through sockets. Both the device and the driver have designated "well known" areas in their memories, which are used as mailboxes to exchange messages. Such an area on the C-5 NP is called the HCA (Host Communication Area). The device object for the device initializes socket data structures in the HCA and places the interrupt information there as well. The interrupt handling code on the C-5 looks in this area when an interrupt occurs. The interrupted entity retrieves the socket id and services the interrupt based on the interrupt arguments passed in the socket.



Simulator Bus ObjectThe simulator bus object serves the function of redirecting the bus accesses made by objects connected to it towards the user space. The object actually passes the accesses on to the simulator device object, which passes it on to the user space via the end-point mechanism.

Simulator Device ObjectThe simulator device object serves the purpose of binding with the simulator bus object and thus gets access to the redirected bus accesses in the user space. It also satisfies incoming accesses from the user space by passing these on to the simulator bus object. Figure 11 depicts the simulator device and bus objects and the connection between the user program and the simulator.

Figure 11 Simulator Bus and Device Object

C5 Device

User Program

Simulator Bus

Simulator Device

Simulator Stub PCIsrv

Driver

TCP/IP

Simulator


Porting and Configuration 109

Porting and Configuration This section describes the porting and configuration of the DDK to various OSs. The configuration parameters allow the users to supply key parameters for the driver that are most suited to the particular project. The parameters also have a direct impact on the memory usage of the driver. The users may modify the configuration parameters to obtain the desired balance between performance and resource usage.

Porting The driver framework is flexible enough to be ported to OSs with different characteristics. One of the first issues that needs to be addressed concerns the decomposition of the driver across the kernel space and user space (that is, if the OS has such a notion). Almost any configuration of this decomposition is possible by varying the implementation of OSAL.

Available porting resources are:

• User space port for VxWorks.

• Kernel space / User Space port for Linux

• User space port for a POSIX system

Port OSALOSAL comprises of the OS-specific primitives and the common utility code (also known as the platform code) in the platform layer. Only the OS-specific primitives need to be ported. The OSAL is located at services\osal.

The OSAL and platform code interface is located at services\osal\inc.

The OS-specific implementation is in the corresponding directories below the main directory.

services\osal\ppcVxworks

services\osal\Linux

The platform code is located at services\osal\pform.

Naming ConventionThe naming convention is to use the prefix “os” for OSAL primitives, “pf” for platform code primitives and the suffix “K” for the kernel version of the OSAL. Furthermore, the pre-processor constant CPORT_KERNEL is defined equal to “1” for kernel space.



User Space and Kernel Space SeparationThe driver framework is separated into code that runs above the line labeled “kernel boundary” in Figure 6 and the code that runs below that line. The two parts of the code are located at: drivers\np\usr and drivers\np\src.

The two parts of the code are connected to each other through the OSAL device interface specified in services\osal\inc\osDev.h.

This arrangement allows the code to be separated into the user space and kernel space for OS and implementations that demand that. Whether it is or not depends on the implementation of the OSAL device interface for that OS. The implementation for Vxworks and Linux are located at:

drivers\np\os\ppcVxworks\osDev.c

drivers\np\os\Linux\osDev.c

The Linux version maps the OSAL device interface to the Linux device interface. The Vxworks version maps the device interface directly to the raw driver code. If the driver code is separated into the user space and kernel space, then two versions of OSAL must be implemented – a user space version and a kernel space version. The Linux version of OSAL does this. It is located at services\osal\Linux.

OSAL PrimitivesOSAL comprises abstractions of common OS primitives. Table 7 lists the various classes of primitives and the corresponding files that define them.

Table 7 OSAL Primitives

device interface osDev.h

deferred processing routine osDpr.h

driver utility functions osDrv.h

initialization osInit.h

interrupt services osIntr.h

logging services osLog.h

memory management osMem.h


Porting and Configuration 111

Implement OS-specific Kernel Porting LayerWhen the user space code and kernel space code are separated, the kernel space code is packaged into an OS-specific device driver. The driver code needs to be wrapped up into the shape and form expected by the specific OS. Furthermore, the calls from the user space are dispatched to the device driver in an OS-specific way. These need to be mapped to the interface implemented by the driver.

The Linux version of this kernel porting layer is located at drivers\np\os\Linux\osModule.h.

Implement OS-specific DDK ComponentsThe driver framework also expects some OS-specific components to be implemented. These components are specified in:

drivers\np\os\osBusPci.h

drivers\np\os\osStart.h

The meaning of the PCI bus object is obvious. The file osStart.h specifies the driver entry points for an OS that requires one.

queues osQueue.h

semaphores osSem.h

system stubs osSys.h

tasking osTask.h

time services osTime.h

timer services osTimer.h

Table 7 OSAL Primitives



Configuration The various driver configuration parameters are located in drivers\np\os\osConfig.h.

These parameters are described in Table 8.

Table 8 Configuration Parameters

OS_DPR_MAX maximum deferred processing routine (DPR) queue size

OS_NAME_LEN_MAX maximum length of names

NP_RSHELL_PORT port number for the remote shell service

NP_EP_MAX maximum number of end-points for all devices

NP_C5_MAX maximum number of NPs

NP_C5_PORT_MAX maximum number of user ports

NP_SIM_MAX maximum number of simulated devices

NP_C5_PRINTF_MSG_MAX number of buffers in the printf socket

NP_C5_MSG_MAX number of buffers in the msg socket

NP_C5_DMA_MSG_MAX number of buffers in the DMA socket

NP_C5_DMA_BUF_MAX maximum number of DMA buffers

NP_C5_DMA_BUF_LEN maximum size of DMA payload

NP_C5_DMA_BUF_VEC number of DMA buffers in a vector

NP_C5_DMA_CTL_LEN maximum DMA control message length

NP_C5_RPC_MAX maximum RPC types

NP_C5_RPC_LEN maximum length of RPC types

NP_C5_XP_REQ_MAX maximum types of XP Requests

NP_DEV_MAX maximum number of device objects

NP_CMD_TBL_MAX maximum number of command tables in the shell


Device Driver API 113

Device Driver API This section describes the Host Services API. An instance of the API exists on both the host and the chip. On the host the API enables the users to write applications that control various devices in the NP family. On the chip the API is used to communicate with the entities on the host. Fairly complex applications that have components distributed across the host and the chip can be designed using the primitives in the API.

Organization The Host Services API is broken down into categories of service. First the overall programming model / usage model for the service is presented. Then the syntactic details of the various primitives are presented. Some of the services are orthogonal with respect to the host and the chip. In such cases the calls are described together.

Host Services API The API is located in drivers\np\usr\hsApi.h.

All of the routines discussed here return values of the type HsStatus.

Please ignore the macro "HS" used in the file. It is for internal use only.

Base APIThe user must initialize the API before making any other calls. On the host the user may be working with more than one NP device. Obtain a descriptor for the device using the open API and dispose of this descriptor using the close API.

hsInit()

Description Initialize the API.

Signature int hsInit (void);

CPU Host, NP

Arguments (IN) None


Returns HsStatus of the operation.

Caveats None




hsOpen()

hsClose()

Port InterfaceThe port interface is the primary communication mechanism between the entities on the host and the chip. The user simply opens a port on a device and then writes and reads messages to and from the port.

The API is nearly the same on the host and the chip, except that there are no parameters for the NP descriptor and timeout on the chip.

Description Obtain a descriptor for the specified device.

Signature int hsOpen (HsNpDesc* np, const char* name);

CPU Host

Arguments (IN) None

Arguments (OUT) np – Descriptor for the specified device.name – Name of the specified device


Caveats None


Description Dispose of the specified device descriptor.

Signature int hsClose (HsNpDesc np);

CPU Host

Arguments (IN) np – Descriptor for the specified device.



Caveats None




hsOpenPort()

hsClosePort()

Description Open a port on the specified device.

Signature on the Host int hsOpenPort (HsPortDesc* port, int id);

Signature on the NP int hsOpenPort (HsPortDesc* port, HsNpDesc np, int id);

CPU Host, NP

Arguments (IN) np – Descriptor for the specified device (host only).id – port identifier.

Arguments (OUT) port – Port descriptor returned to the user.


Caveats Note that the NP device descriptor must be omitted when this routine is used on the chip.


Description Close a port on the specified device.

Signature int hsClosePort (HsPortDesc* port);

CPU Host, NP

Arguments (IN) port – Port descriptor returned to the user.



Caveats None




hsReadPort()

hsWritePort()

Description Read from the specified port.

Signature on the Host int hsReadPort (HsPortDesc port, void* buf, int len, int ms);

Signature on the NP int hsReadPort (HsPortDesc port, void* buf, int len);

CPU Host, NP

Arguments (IN) port – Port descriptor returned to the user.buf – Buffer to read the message into.len – Length of the buffer.ms – Timeout in milliseconds (Host only).



Caveats Note that the timeout parameter must be omitted when this routine is used on the chip.


Description Write to the specified port.

Signature int hsWritePort (HsPortDesc port, void* buf, int len);

CPU Host, NP

Arguments (IN) port – Port descriptor returned to the user.buf – Buffer containing the message to write.len – Length of the buffer.



Caveats None




Packet InterfaceThe packet interface provides a mechanism for bulk data (packet) transfer between the host and the chip. The packet service utilizes DMA to transfer large amounts of data efficiently.

The programming model is that the packet is deemed to have two parts. The control part, which is small in size, and the payload, which is significantly larger. The user derives a type from the base packet type NpC5Pkt. He assembles the control data into this type, appending it at the end of the base type NpC5Pkt. He obtains a packet buffer using one of the API routines and assembles the payload into that buffer. He adds the buffer descriptor to the header of the packet type. The packet is then passed to the packet write routine. The packet interface transfers the packet over to the other side where the user reading the packet interface receives both the control part and the payload.

To use the packet interface the user must first open a port and set it into the packet mode.

Note that on the chip the payload is stored in a BMU buffer.

Figure 12 User-defined Packet Type



hsOpenPkt()

hsClosePkt()

Description Set the specified port into packet mode.

Signature int hsOpenPkt (HsPortDesc port);

CPU Host, NP

Arguments (IN) port – Port descriptor.



Caveats None


Description Reset packet mode on the specified port.

Signature int hsClosePkt (HsPortDesc port);

CPU Host, NP

Arguments (IN) port – Port descriptor.



Caveats None




hsReadPkt()

hsWritePkt()

Description Read a packet from the specified port.

Signature on the Host int hsReadPkt (HsPortDesc port, NpC5Pkt* pkt, int len, int ms);

Signature on the NP int hsReadPkt (HsPortDesc port, NpC5Pkt* pkt, int len);

CPU Host, NP

Arguments (IN) port – Port descriptor.pkt – Pointer to the user-defined packet type.len – Length of the user-defined packet type.ms – Timeout in milliseconds (Host only).



Caveats Note that the timeout parameter must be omitted when this routine is used on the chip.


Description Write a packet to the specified port.

Signature int hsWritePkt (HsPortDesc port, NpC5Pkt* pkt, int len);

CPU Host, NP

Arguments (IN) port – Port descriptor.pkt – Pointer to the user-defined packet type.len – Length of the user-defined packet type.



Caveats None




hsAllocPktBuf()

hsFreePktBuf()

Description Allocate a packet buffer on the specified device.

Signature on the Host int hsAllocPktBuf (HsNpDesc np, NpC5BufDesc* buf);

Signature on the NP int hsAllocPktBuf (NpC5BufDesc* buf);

CPU Host, NP

Arguments (IN) np – Device descriptor (Host Only).

Arguments (OUT) buf – Packet buffer descriptor returned to the user.




Description Free a packet buffer on the specified device.

Signature on Host int hsFreePktBuf (HsNpDesc np, NpC5BufDesc* buf);

Signature on the NP int hsFreePktBuf (NpC5BufDesc* buf);

CPU Host, NP

Arguments (IN) np – Device descriptor (Host Only).buf – Packet buffer descriptor.







hsAllocPktBufVec()

hsFreePktBufVec()

Description Allocate a packet buffer vector on the specified device.

Signature int hsAllocPktBufVec (HsNpDesc np, NpC5BufVec* buf);

CPU Host

Arguments (IN) np – Device descriptor.

Arguments (OUT) buf – Vector of packet buffer descriptors returned to the user.


Caveats None


Description Free a packet buffer vector on the specified device.

Signature int hsFreePktBufVec (HsNpDesc np, NpC5BufVec* buf);

CPU Host

Arguments (IN) np – Device descriptor.buf – Vector of packet buffer descriptors.



Caveats None




Package HandlingThe following two primitives are used to load a package of code onto the chip and manage this package.

hsPackageLoad()

Description Load a package of code on to the chip.

Signature int hsPackageLoad (HsNpDesc np, void* pkgData, const int count, int bootFlags, int arg0, int arg1, int arg2, int arg3);

CPU Host

Arguments (IN) np – Device descriptor.pkgData – Package.count – Length of package.bootFlags – Passed to the package boot process on the chip.arg0 - arg3 – Passed to the package on the chip.



Caveats None

Implementation Notes A successful return means only that the package is loaded and started.



hsSymbolImport()

Remote Procedure CallThe Remote Procedure Call mechanism allows code executing on the host to call procedures on the chip. The arguments passed to the call on the host are marshaled and transported to the chip, the handler of the RPC is located on the chip and executed with the arguments and the return value is then marshaled and sent back to the host. The call on the host returns at this point with the return value obtained from the handler on the chip.

The programming model is that the user derives a user-defined RPC type from the base type NpC5Rpc, defines a handler for the RPC on the chip, and registers it using the API. The user then invokes the RPC routine on the host. The procedure on the chip is executed remotely as described above.

Description Import a variable from a package.

Signature int hsSymbolImport (HsNpDesc np, char* name, void** value);

CPU Host

Arguments (IN) np – Device descriptor.name – Name of the exported variable in the package.

Arguments (OUT) value – Address of the variable in a form that can be used by hsWriteMemory().


Caveats None




Figure 13 User-defined RPC Type

hsRpc()

Description Execute a remote procedure call on the NP.

Signature int hsRpc (HsNpDesc np, NpC5RpcProcId proc, NpC5Rpc* rpc, int len);

CPU Host

Arguments (IN) np – Device descriptor.proc – Procedure identifier.rpc – Pointer to the user-defined RPC type.len – Length of the user defined RPC type.



Caveats None




hsRpcProcReg()

hsRpcProcUnreg()

XP RequestThe XP request is a remote procedure call that is made available for legacy compatibility.

Description Register a remote procedure call on the NP.

Signature int hsRpcProcReg (NpC5RpcProcId id, NpC5RpcProc proc);

CPU NP

Arguments (IN) id – Procedure identifier.proc – Handler for the RPC.



Caveats None


Description Unregister a remote procedure call on the NP.

Signature int hsRpcProcUnreg (NpC5RpcProcId id);

CPU NP

Arguments (IN) id – Procedure identifier.



Caveats None




hsXpRequest()

hsXpReqHndlrReg()

Description Launch an XP request.

Signature int hsXpRequest (HsNpDesc np, NpC5XpReqOp opcode, int* arg1, int* arg2, int* arg3, int* arg4,);

CPU NP

Arguments (IN) np –Device descriptor.opcode – XP request operation identifier.arg1 - arg4 – arguments.



Caveats None


Description Register an XP request on the NP.

Signature int hsXpReqHndlrReg (NpC5XpReqOp opcode, NpC5XpReqHndlr hndlr);

CPU NP

Arguments (IN) opcode – Procedure identifier.hndlr – Handler for the XP request.



Caveats None




hsXpReqHndlrUnreg()

Low Speed Serial InterfaceThe following two primitives are used on the host to read from and write to the LSSI bus.

hsReadLssi()

Description Unregister an XP request on the NP.

Signature int hsXpReqHndlrUnreg (NpC5XpReqOp opcode);

CPU NP

Arguments (IN) opcode – XP request operation code.



Caveats None


Description Read from the LSSI bus.

Signature int hsReadLssi (HsNpDesc np, uint16 addr, uint16* data);

CPU Host

Arguments (IN) np – Device descriptor.addr – Address of the LSSI device.data – Buffer the data is to be read into.



Caveats None




hsWriteLssi()

Utility FunctionsThe following routines provide the capability to read from and write to the device memory space, configuration space, and registers.

hsReset()

Description Write to the LSSI bus.

Signature int hsWriteLssi (HsNpDesc np, uint16 addr, uint16* data);

CPU Host

Arguments (IN) np – Device descriptor.addr – Address of the LSSI device.data – Data to write.



Caveats None


Description Reset a device.

Signature int hsReset (HsNpDesc np);

CPU Host

Arguments (IN) np – Device descriptor.



Caveats None




hsReadMemory()

hsWriteMemory()

Description Read from memory space.

Signature int hsReadMemory (HsNpDesc np, uint32 address, void* buffer, uint32 count);

CPU Host

Arguments (IN) np – Device descriptor.address – Address to read.buffer – Buffer to read into. count – Length of the read buffer.



Caveats None


Description Write to memory space.

Signature int hsWriteMemory (HsNpDesc np, uint32 address, const void* buffer, uint32 count);

CPU Host

Arguments (IN) np – Device descriptor.address – Address to write.buffer – Buffer with the data to write. count – Length of the data.



Caveats None




hsReadCfgMemory()

hsWriteCfgMemory()

Description Read from configuration memory.

Signature int hsReadCfgMemory (HsNpDesc np, uint32 address, void* buffer, uint32 count);

CPU Host

Arguments (IN) np – Device descriptor.address – Address to read.buffer – Buffer to read into. count – Length of the read buffer.



Caveats None


Description Write to configuration memory.

Signature int hsWriteCfgMemory (HsNpDesc np, uint32 address, const void* buffer, uint32 count);

CPU Host

Arguments (IN) np – Device descriptor.address – Address to write.buffer – Buffer with the data to write. count – Length of the data.



Caveats None




hsReadRegister()

hsWriteRegister()

Description Read from a register.

Signature int hsReadRegister (HsNpDesc np, uint32 offset, uint32* buffer);

CPU Host

Arguments (IN) np – Device descriptor.offset – Register offset to read.buffer – Buffer to read into.



Caveats None


Description Write to a register.

Signature int hsWriteRegister (HsNpDesc np, uint32 offset, uint32* data);

CPU Host

Arguments (IN) np – Device descriptor.offset – Register offset to write.data – Buffer with the data to write.



Caveats None




PollingThe chip side of the host services is designed to use polling to gather events occurring on the host interface. The user is required to call the provided polling function continuously in a loop for the API to work.

hsPoll()

SignalingThe code on the chip can send signals to the host. The signals are defined in drivers\np\src\npDevC5Share.h. The corresponding signal handler in the driver is invoked.

hsSignal()

Description Poll for host interface events.

Signature int hsPoll (void);

CPU NP

Arguments (IN) None



Caveats None


Description Send signals to the host.

Signature int hsSignal (int signal);

CPU NP

Arguments (IN) signal – Signal value.



Caveats None



The Portable Device Driver 133

The Portable Device Driver

The portable device driver is kernel-resident. It is accessed via the Host Services API in the user space. The driver can be built on any Linux machine running a 2.4 kernel. It may be used to connect to a simulated C-Ware NP.

Linux Driver Source Code Table 9 lists the Linux device driver software components and their locations

Table 9 Linux Driver Source Code Components and Locations

COMPONENT COMPONENT LOCATION (IN CST INSTALLATION)

Source Code Base drivers/np

Kernel Space Code drivers/np/src

User Space Code drivers/np/usr

OS Specific Code drivers/np/os

Linux-specific Code drivers/np/os/Linux

Linux Driver Build Directory drivers/np/os/Linux/drv

Linux User Build Directory drivers/np/os/Linux/usr

OSAL services/osal

OSAL Interface services/osal/inc

OSAL for Linux services/osal/Linux

OSAL Platform Layer services/osal/pform



Connecting to the NPSimulator

Use the following steps to connect to the NP Simulator

1 Create a simulator config file and insert the following commands in the file:

DcpInstance 0PciDeviceName DCP_3PciConnectImmediate falsePciDcpSlot 3PciHostSlot 0PciTest trueFastMemcpy falseFastImemcpy falseFastMemset false

To avoid confusion with other config files, it is best to store this config file in the /bin directory and start the Simulator from the /bin directory.

2 Start the Simulator on a platform supported by the Simulator (win32 or Solaris) as follows:

a In a command shell window, enter

> pcisrv -v

b In a second command shell window, enter

> cwsim

c Enter go at the prompt.

3 Connect to the simulator by executing the command simulator in the NP shell as follows:

> simulator hostname

or

> simulator -b hostname

or

> simulator -l hostname

The options -b and -l are used to indicate the endian-ness of the machine that the simulator is running on. No option indicates the same endian-ness as the driver. Use -b


The Portable Device Driver 135

for big-endian machines, such as Sun, and -l for little-endian machines, such as PCs running Windows.

4 Once connected to the simulator the simulated NP devices may be used like a normal NP device. The default name for the device is np0 or dcp0. The instance of the simulated device can be controlled by passing the -i option to the simulator command:

DCP> simulator -i 3 hostname

The above command will create the device np3 or dcp3 and connect to a simulator running on a little-endian machine.

5 Other shell commands may be invoked as follows.

DCP> sysinfo np0DCP> rd np0 0xbd803800DCP> packload np0 package





CSTHAPG-UG/D

Rev 13
Chapter 6
PROGRAMMING EARLIER VERSIONS OF THE C-5 DEVICE DRIVER

Overview This chapter contains information on the device driver distributed with versions of CST previous to CST 2.3. CST 2.3 included a new device driver, although the driver documented in this chapter was also included in the CST version for use with certain applications. For information on the new device driver and on those applications that still require the old driver, see Chapter 5.

As an alternative to the Host API routines, host applications can programmatically interact with the C-Port C-5, C-5e, or C-3e Network Processor (NP) more directly and at a lower level of functional abstraction via the C-5 Device Driver software.

The C-5 Device Driver provides a working, reference implementation of code that controls a C-Port NP device. You can use the Driver’s components as implemented, or you can write your own equivalent driver software from scratch with this Driver as a model.

The C-5 Device Driver performs the following basic functions:

• Initialization of the NP — Operations for setting up host-related registers (Base Address Registers, Host Communication Area, and so on) on the NP, packloading software into the NP, starting software on the NP, and resetting the NP.

• Automatic PCI bus device enumeration — Automatically finds all physically connected C-5 Switch Modules (or C-5e Switch Modules) on the PCI bus.

• PCI bus mediated operations — Memory-mapped access, transparent byte-swapping, host interrupts of the XP and vice versa, redirection to the C-Ware Simulator.

• Read/Write of N P memory — Reading from and writing to discrete memory locations on the NP. Both DMA and programmed I/O techniques are supported.

This chapter presents:

• Brief overview of the Driver’s functional characteristics and required hardware environment

CSTHAPG-UG/D REV 13

138 CHAPTER 6: PROGRAMMING EARLIER VERSIONS OF THE C-5 DEVICE DRIVER

• Explanation of the Driver’s implementation

• Description of the Driver’s PCI Interface functionality, including transparent byte-swapping and NP to host address translation functionality

• Description of the Driver’s interrupt support functionality

• Reference description of the most significant public methods provided inthe dcpMgr class

This chapter assumes the reader is already familiar with the principles of device driver design.

Software Deliverable The C-5 Device Driver is built into the vxWorks image file that is shipped with the C-Ware Software Toolset.

For information about building the C-5 Device Driver component, see the section “Building the C-5 Device Driver Library” on page 38.

Functional Overview Notice the following functional characteristics of the C-5 Device Driver software:

• The C-5 Device Driver is not implemented nor delivered as a “true” device driver. See the section “Implementation of the Driver” on page 139.

• By convention, the Driver uses a set of default settings for NP registers for “streamlined” PCI bus operations between host and the NP.

• The Driver uses host memory as management buffers.

• The Driver uses interrupts from the NP’s XP to the host processor and from the host processor to the NP’s XP.

• The Driver minimizes the use of the NP XP’s IMEM for non-critical operations.

The host processor’s Single Board Computer includes:

• Freescale Power PC general-purpose microprocessor

• Host DRAM - extended memory that can be referenced by the NP via the PCI bus


Implementation of the Driver 139

• Raven PCI Bridge - PCI bridge used on the host SBC to arbitrate access between the PCI backplane bus and the host processor and memory. It also provides access to little-endian devices on the host SBC, so it does byte-swapping of all data that passes through it. The Raven chip also does an address translation of its own on all PCI accesses that pass through it.

The C-5 Switch Module board (or C-5e Switch Module) is populated with SDRAM. The host processor can access this SDRAM as off-chip memory using DMA engines in the NP chip. It is used for extended buffer management by the NP.

Implementation of the Driver

The C-5 Device Driver provides a set of C language programming interface routines. These routines, in turn, call lower level routines implemented as public methods of a C++ language class. These public methods implement clusters of functionality at both higher and lower levels of functional abstraction, to allow the application developer great freedom to evaluate various tradeoffs of design and implementation.

The C-5 Device Driver’s C language and C++ language programming interfaces, as a set or individually, might change in future releases of the C-Ware Software Toolset and the C-Ware Development System.This is equivalent to a “proposed” support status, as described in the C-Ware APIs User Guide document.

The C-5 Device Driver is intended to be operating system neutral and is suitable for porting to various operating system environments. The Driver’s classes can easily be incorporated into a true device driver for environments that do not allow user code to directly access memory and I/O devices.

Be aware that the C-5 Device Driver implements a few direct references to the vxWorks operating system. For example, the Driver calls VxWorks to register interrupt handlers.

Because the Driver is intended to be distributed to C-Port customers and to be modified by them, it has been implemented with an emphasis on simplicity. There are places in the Driver’s code where tradeoffs are made between simplicity and optimzation of code speed. In most instances the Driver opts for simplicity with a reasonable level of code and resource efficiency. It is expected that the customer will perform the final optimization steps for the application’s or product’s specific needs.



Driver Data TransferMechanisms

Several CST development tools require a means of passing data between the host and the NP. For example:

• The PrintfListener software requires this capability for passing standard output calls to the host processor for display to the user.

• The C-Ware Debugger requires bi-directional data flow for passing debug requests and information between the host processor and the NP.

Most host processor applications also require a means of transferring control and data between the host processor and the NP. The Driver makes available a data transfer mechanism that is extensible for user applications and that offers different mechanisms for transferring different volumes of data, as follows:

• A pipe construct offers a control transfer mechanism using programmed I/O.

• A high-volume data transfer mechanism uses DMA to transfer quickly a large chunk of data and with less impact on system resources.

Thus, the Driver itself enables the infrastructure behind the PrintfListener and the C-Ware Debugger to operate and also provides a more general data transfer mechanism that can be incorporated into host applications.

Because the Driver provides the data transfer mechanism used by the CST’s software development tools themselves, you cannot set a Debugger breakpoint within the code path for your application’s data transfers. Doing so would impair the functionality of the tools themselves.

Comparison of DriverVersions

The C-5 Device Driver is designed to provide a basis for production applications. It offers improved simplicity and performance compared to previous Driver versions.

Unlike previous versions of the Driver, it now allows a signficant portion of a host application’s NP control logic to be performed by the host processor itself, where resources of code space and computation power are more plentiful.

The Driver now also reduces the XP IMEM used on the NP for non-critical time operations. Because XP IMEM is a critical NP resource, its use should be reserved for functions that are in the application’s forwarding data path. The Driver’s design has moved logic from the XP to the host processor by making the access routines more efficient.

Finally, previous C-5 Device Driver versions were designed to support a user who is experimenting with various ways of controlling the subcomponents of the NP. It was


Implementation of the Driver 141

designed to facilitate the process of discovery, so simplicity and run-time performance were not top priorities.

Table 10 on page 141 presents the differences between the C-5 Device Driver available for CST Version 1.7 (and later) and previous Driver versions.

Table 10 Feature Comparison Between the Versions of the C-5 Device Driver

FEATURE C-5 DEVICE DRIVER (CST VERSION 1.7 AND LATER) PREVIOUS DRIVER RELEASES

True device driver? No; the component is a C++ class that can be called by a true driver.

Yes; the component is installed in the host operating system and provides ‘standard’ entry points.

Facilitating PCI accesses Provides default settings for registers for streamlined PCI accesses.

Checks and sets up registers for each PCI reference.

Location of memory management buffers

Uses host memory. Uses NP memory.

Use of interrupts Uses interrupts from the NP Executive Processor to the host and from the host to the Executive Processor.

Polls for events and does not use interrupts.



PCI Interface Functionality Virtually all data transferred between the NP and the host processor travels over the NP’s PCI Bus Interface. The NP is specifically designed to optimize the use of this interface for data transfers. This section assumes that the reader is already familiar with the published PCI standard.

NP Base AddressRegisters

The NP has a set of registers that configure the address ranges that are used to map external PCI devices. This register set is organized in pairs that include a Base Address Register (BAR) and a Translation Register (XLAT). The BAR is used to tell the NP what addresses to decode from the PCI bus. The corresponding XLAT register is used to swap out the high order bits of the decoded address and substitute another set of bits that map the decoded address into a new address range.

There are two inbound BARs that allow the NP to configure where in PCI address space the NP will appear to external devices. There are eight outbound BARs that allow the NP to configure the address range that it will use to reference external devices.

Each BAR pair can be configured to map a selectable sized window of addresses into PCI space from 16KBytes to 2MBytes of address space. All BARs in our application are configured to be 1MByte windows. The address value programmed into any BAR should be BAR-size aligned. That means if your BAR size is 1MByte, the start address should be 1MByte aligned.

Don’t store values in BARs that represent overlapping memory regions. This can cause the calling application to waste a part of the NP’s available range of PCI addresses.

Four-Byte Data Transfers Every read and write over the PCI bus transfers increments of 4Bytes of data. Certain C-Port NPs don’t support 1Byte or 2Byte data transfers. That is, every transfer address on both the host processor and the NP must be 4Byte aligned. For any request to the PCI interface the designated length must also be 4Byte aligned. The NP’s PCI Bus Interface does not attempt to provide support for non-aligned addresses or lengths.

The C-5 Device Driver’s data transfer routines validate the alignments and lengths for all address values in all read and write data transfers.


PCI Interface Functionality 143

Byte Ordering The C-Port NP is a big-endian processor. The PowerPC processor is also a big-endian processor. However, the Raven MPIC controller on the CDS Host Application Module as a PCI-to-PCI bridge converts data into little-endian format to accommodate other on-board components. For C-Port NP chips prior to C-5 NP Version D0, the PCI interface software between the host processor and the NP needs to swap the bytes on each transfer. For the C-5 NP Version D0 chips, this software functionality not necessary, as the chip can be configured to perform this task transparently.

Memory-Mapped Access The PCI interface provides primitives for the host processor to read and write from/to locations in PCI address space. Using these primitives, the NP registers and memory are presented to the host processor as memory-mapped references. The C-Ware Software Toolset installation provides definitions of locations and specific registers in NP memory space in C language header files found in this directory:

services\chip\inc\

Memory Reference ByHost Processor to NP

See in Figure 14 on page 144 the steps that occur for the host processor to perform a BAR-arbitrated memory reference into NP memory.

In order for the host processor to write data to the NP’s DMEM address 0xBD804384, these steps are performed (some performed by the C-5 Device Driver):

1 The host processor program allocates a pointer variable and assigns an address value to it.

2 The Raven PCI bridge swaps the order of the data bytes.

3 The Raven PCI bridge applies its mapping to the address and places the value on the PCI backplane bus.

4 The NP’s PCI Bus Interface decodes the address reference from the PCI bus.



Figure 14 Low-Level Operations for Host Processor to Write to C-Port NP Memory

5 The NP translates the decoded address, via the BAR and XLAT register pair configured for the address range specified in the decoded PCI address, to an internally mapped value.

6 The translated memory location (in this case, in the NP XP’s memory) is updated.

6

ptr = oxC1D04384;

*ptr = 0x11223344;

Host Single Board Computer

Freescale Power PC PPC750

Raven Bridge

Addr + 0x40000000

0x01D04384

1

2

3

PCI bus

C-5 Switch Module

C-5

XLAT

BAR

0xBD80

0x01D0

DRAM

0x44332211

4

50xBD804384


PCI Interface Functionality 145

Inbound Address MappingConventions

Because the NP’s internal address space is greater than 2MBytes, it might be necessary to alter the contents of an inbound BAR to reference portions of the NP internal address space, such as the QMU, and certain Channel Processor memories.

The C-5 Device Driver’s routines used the following register conventions:

• Inbound BAR0 references DMEM24 and XP registers

• Inbound BAR1 references DMEM25

• Inbound BAR0 is configured static to support interrupts.

• Inbound BAR1 is configured dynamic and can be changed to reference the QMU, the Channel Processors, and so on.

• The C-5 Device Driver’s methods maintain the address offsets so that they compensate for the Raven PCI bridge chip’s mapping and correspond to the programmed values in the NP XP’s registers.

The C-5 Device Driver provides methods for updating the NP’s inbound BARs so that these settings can be managed by the host application.

The C-5 Device Driver does not provide any locking mechanism to avoid references that are invalidated due to overriding the default register settings. (However, the Host API routines hsRead* and hsWrite* do provide that protection. See Chapter 3. )

Outbound AddressMapping Conventions

The CDS Host Application Module’s on-board memory is accessible by the NP for use as secondary buffer storage or as a shared memory communications mechanism. You configure the NP’s eight outbound BARs to enable the NP to address host-based memory.

When the C-5 Device Driver is initialized, it sets up the NP’s outbound BARs as follows:

• Configures eight independent 1MByte windows into host-based memory starting at an address designated by the calling program. Each window can point to global variable space or could be a region on the heap, to allow the NP to reference objects that had been malloc’ed by the host processor program. It is also possible to configure the BARs so that a region of global space and a region of heap space can be referenced.

• The default outbound BAR settings allow physically separate regions of host-based memory to appear as contiguous to the NP XP.



Memory Reference By NPto Host Processor Memory

See in Figure 15 on page 146 the steps that occur for the NP XP to perform a BAR-arbitrated memory reference to host processor memory.

In order for the NP’s XP to write data to host memory at address 0x90248C40, these steps are performed (some performed by the C-5 Device Driver):

1 The NP’s XP sets up a pointer and assigns a value to it.

2 NP arbitration logic translates the address as per an outbound BAR/XLAT register pair.

Figure 15 Low-Level Operations for the NP’s XP to Write to Host Processor Memory

3 The NP’s PCI Bus Interface uses the BAR/XLAT register pair to map the host memory reference, then places the mapped reference on the PCI backplane.

4 The Raven PCI bridge decodes the received address and swaps the data.

5 The Raven PCI bridge maps the received address to a host memory address.

6 Data is assigned to the host memory location.

Host Single Board Computer

PCI bus

C-5 Switch Module

C-5

XLAT

BAR

0x8020

0x9020

3

XP

ptr = 0x90248C40;*ptr = 0x11223344;

1

2

0x80248C40

DRAM

0x44332211

Raven Bridge

0x0100 >

0x0200 >

0x0300 >

0x0400 >

0x00248C40 >

4

5 +0x8000

6


Interrupt Functionality Support 147

Interrupt Functionality Support

A host application program can use interrupts to enable it work in an event-driven mode, as opposed to polling the PCI bus to detect events. Using event-driven operation also reduces the amount of traffic on the overall system’s PCI bus.

NP’s XP Interrupts to theHost Processor

In the NP XP’s DMEM there is a memory region called the Host Communication Area (HCA) that is reserved for host-relevant data structures. One of these is an interrupt_reason field whose value indicates the reason for an interrupt from the NP to the host processor. The C-5 Device Driver follows a convention of having the XP set this field when asserting an interrupt to the host processor, and the field is cleared by the host processor after it has serviced that interrupt.

Asserting an Interrupt to the Host The NP XPRC program should use the Host API routine hsSignalHost() to assert an interrupt directed to the host processor.

hsSignalHost() prevents interrupt overrun by blocking any calling XPRC context until it sees that the XP HCA’s interrupt_reason field is clear. When hsSignalHost() is invoked, if it determines that no interrupt to the host processor is pending, it sets the XP HCA’s interrupt_reason field then asserts the NP’s external interrupt pin by writing the XP_INTERRUPT_HOST pin in the xpuToCpInterrupt register.

Event Notification The dcpMgr::Open() method creates a semaphore for each valid interrupt-reason for a given NP device.

The Interrupt Service Routine (ISR) in the dcpMgr class must be coded to read the XP HCA’s interrupt_reason field. (This is the basis for the requirement that an inbound BAR remain mapped to the NP’s DMEM24 region.) The ISR next signals the corresponding semaphore for that interrupt-reason.

A host application program can suspend on the occurrence of a given event by calling the dcpMgr::pendOnEvent() method, which simply pends the caller on the corresponding semaphore.



Clearing the Interrupt The host application program’s Interrupt Service Routine (ISR) must be coded to write a 1 to the XP_INTERRUPT_HOST bit of the NP XP’s XP_AUX_EVENT register. This bit is a “write-1-to-clear” field as demonstrated by the following code sample:

status = pDcp->readRegister(XP_AUX_EVENT, &auxEventBits);

intmask = XP_INTERRUPT_HOST; status = pDcp->writeRegister(XP_AUX_EVENT, intmask);

/*Clear interrupt-reason mask to signal the XP. */pDcp->hcaWrite(offsetof(HCA, InterruptReasonMask), 0);

This code clears the interrupt to the NP hardware, so the ISR must also clear the XP HCA’s interrupt_reason field to satisfy the Host API software convention.

Host Processor Interruptsto the NP’s XP

The NP Executive Processor (XP) contains eight mailbox registers that are writable by the host processor. When the host processor writes a value to a specific mailbox register, the NP hardware invokes a specific vector. Default vector handlers are installed automatically by the package loading logic. (The default vector handler behavior is to “printf” the interrupt occurrence then drop it.) The value written to the mailbox register is set up in the appropriate register so that the vector handler code can reference it as an argument to a function call.

Setting a Mailbox Register Vector The initialization code for an XPRC program that uses mailbox-based interrupts should set any mailbox vectors before the host application program attempts to assert one.

There is a Host API routine for installing a specific mailbox register vector, such as this line of code:

status = setPciMailboxVector(HOST_MAILBOX_INDEX, hostRequestVec);


Interrupt Functionality Support 149

Asserting a Mailbox Register Interrupt to the XPThe host processor can assert an interrupt to the NP’s XP by writing any value to the desired PCI_MAILBOX register. This value is passed to the mailbox interrupt vector handler as a formal parameter. For example, the host application program would perform this line of code:

pDcp->writeRegister(PCI_INMAILBOX3, reqAddr);

Executing a Mailbox Register Interrupt Vector Handler Observe these constraints on the code for a mailbox interrupt vector handler:

• Do not make system service call from vector handler code. Most system service calls can cause the calling context to block. If this occurs for an interrupt, the XP will lock up.

• Do not set C-Ware Debugger breakpoints within the vector handler code. The Debugger utilizes interrupts for its own functionality, so setting a breakpoint within the vector handler code causes the current Debugger session to halt and will require a NP reset.

A recommended approach to coding your vector handler is for it to pickup the mailbox value and immediately store it in a global variable dedicated to holding mailbox interrupt vector data. To detect interrupt overrun, the interrupt vector handler can test that variable before assigning it; if the handler detects overrun, the XP program can determine the appropriate recovery action. Thus, the “main loop” of the XPRC context can examine the global variable and execute the corresponding code within the context of an interrupt. This allows that code to call system services, and it could be the target of debugging.

Clearing a Mailbox Register Interrupt Vector The host application program’s interrupt vector need not explicitly perform any NP register reads or writes to clear a mailbox register-based interrupt in the hardware; this is done by the system services code that invokes the mailbox register interrupt vector.



High Level Public Methods

The C-5 Device Driver is implemented as a class named dcpMgr that defines both public and private methods. In your C-Ware Software Toolset installation, find the C++ source code for this class in the file:

drivers\np\ppcVxworks\src\dcpMgr.cpp

Each instance of the dcpMgr class abstracts a NP device as an object that represents its state of a distinct NP device. The class’s methods perform activities, such as:

• Configuring the specified NP device after it has been reset, booted, and loaded with software.

• Sending control messages to the NP device that results in processing being performed by the NP’s Executive Processor (XP).

• Receiving the results of NP XP operations.

• Initiating programmed I/O reads and writes from/to the NP device.

• Initiating DMA reads and writes from/to the NP device.

The following sections describe the “high level” public methods implemented in the dcpMgr class’s dcpMgr.cpp source file.

For compatibility with future versions of the C-Ware Software Toolset, we recommend that your host application call these methods via the Host Service API routines documented in Chapter 3. If necessary, you can call these methods directly from your own host application or reimplement them in your own driver code.

Other methods implemented in dcpMgr.cpp are intended to be called by the high level methods described in the following sections.


High Level Public Methods 151

Groups of High LevelPublic Methods

Open/close a handle to a C-Port NP device:

• dcpMgr::Open()

• dcpMgr::Close

Enable/disable the NP Executive Processor:

• dcpMgr::xpEnable()

• dcpMgr::xpDisable()

Read/write NP PCI configuration memory:

• dcpMgr::readCfgMemory()

• dcpMgr::writeCfgMemory()

Read/write NP memory:

• dcpMgr::readMemory()

• dcpMgr::writeMemory()

Initiate a DMA data transfer between host processor memory and NP memory:

• dcpMgr::startDmaToHost()

• dcpMgr::startDmaToDcp()

Detect completion of a previously initiated DMA data transfer between host processor memory and NP memory:

• dcpMgr::dmaToHostSenseDone()

• dcpMgr::dmaToDcpSenseDone()

Other host program operations:

• dcpMgr::loadPackage()

• dcpMgr::pendOnEvent()



dcpTable Array All C-5 Device Driver routines utilize an array whose members are handles to each distinct NP device that are opened during the life of the calling program. As each distinct NP device is opened, the open() method creates an instance of the dcpMgr class and assigns a handle to this instance to one and only one member of the array. This permits all dcpMgr methods to refer to each opened NP device via a unique dcpTable array member number, and allows references to array members to be made during interrupts. (This “array of handles” implementation also permits resource locking, though this functionality is not provided in this CST release.)

The dcpTable array is allocated from the calling program’s static global storage.

Close a Previously OpenedNP Device

dcpMgr::CloseThe dcpMgr::Close() method exists, but its functionality is unimplemented in this release.

Disable XP dcpMgr::xpDisable()

Description Disable the Executive Processor (XP) on the given C-Port NP device.

Signature void dcpMgr::xpDisable (void);

Arguments (IN) None


Returns None

Caveats None




DMA Transfer to HostSense Done

dcpMgr::dmaToHostSenseDone()

DMA Transfer to NP SenseDone

dcpMgr::dmaToDcpSenseDone()

Description Check any outstanding DMA transmit operation for completion. Read the given C-Port NP device’s txStatus and TxCB_Ctl registers for status bits and return them.

Signature int dcpMgr::dmaToHostSenseDone (void);

Arguments (IN) None


Returns 0 – DMA transfer is in progress1 – Idle, or transfer completed without error -1 – Error

Caveats None

Implementation Notes This routine assumes that the DMA transfer started by calling the dcpMgr::startDmatoHost() method that sets up scope and other variables.

Description Check any outstanding DMA receive operation for completion. Read the given C-Port NP device’s rxStatus and rxCB_Ctl registers for status bits and return them.

Signature int dcpMgr::dmaToDcpSenseDone (void);

Arguments (IN) None


Returns 0 – DMA transfer is in progress 1 – Idle, or transfer completed without error -1 – Error

Caveats None

Implementation Notes This routine assumes that the DMA transfer started by calling the dcpMgr::startDmatoDcp() method that sets up scope and other variables.



Enable XP dcpMgr::xpEnable()

Load Package dcpMgr::loadPackage()

For information about the arguments for packloading, see the C-Ware Development System User Guide document.

Description Enable the Executive Processor (XP) on the given C-Port NP device.

Signature void dcpMgr::xpEnable (void);

Arguments (IN) None


Returns None

Caveats None


Description Load a C-Port NP package from the designated file into the designated NP device. This routine uses values that the caller has set up for boot flags and arguments for the package loading activity.

Signature int dcpMgr::loadPackage (char *pkgData);

Arguments (IN) pkgData – Pointer to the caller’s package image. This buffer must contain a valid package image to load.



Caveats The loader in the NP’s Executive Processor (XP) does not perform byte swapping. If the NP’s PCI interface presents bytes in little-endian format, the package data should be byte-swapped before calling this routine.




Open a C-Port NP Device dcpMgr::Open()

Use this method to prepare a NP device for use by all other dcpMgr public methods. The routine creates an instance of the dcpMgr class, which represents the specified NP device and its relevant state information.

This routine performs the following functionality:

• Sets up the member variables with the correct offsets for the designated NP device.

• Reads the PCI configuration space to determine whether the specified device is an actual or simulated NP.

• Calls dcpMgr’s initDcpRegs() method to set the NP in a default state, then initialitzes the NP’s Host Communication Area (HCA), then registers the object’s Interrupt Service Routine (ISR), (that is, dcpMgr::dcpISR()) in the host operating system’s interrupt table.

If the specified NP device has already been opened by another caller, this routine returns its handle as maintained by the C-5 Device Driver’s global dcpTable array. If not, after initializing a new dcpMgr object for the specified NP device, this routine copies that object to the dcpTable array.

Description Open a dcpMgr object for future references to a C-Port NP device. Sets up the new object’s member variables with the correct offsets for the designated NP device.

Signature int dcpMgr::Open (dcpMgr **dcpHandlePtr, int dcpIndex, char* name, int bus, int device);

Arguments (IN) dcpHandlePtr – Pointer to a HsDcpHandle object that is needed for all subsequent calls for this NP device. dcpIndex – Which NP device in the host system: 0 for dcp0, 1 for dcp1, and so on. name – Pointer to a string specifying which NP device to connect to: “dcp0” for dcp0, “dcp1” for dcp1, and so on. bus – PCI bus number where the designated NP device is located. device – Device number on the given bus.



Caveats None




Pend on Event dcpMgr::pendOnEvent()

Use this method to suspend the caller’s task until an interrupt of the designated reason occurs. The caller’s task resumes when the interrupt service routine (ISR) flushes the internally allocated semaphore associated with the designated reason. More than one task can pend on a given reason.

Description Suspend the caller’s task until an interrupt of the designated “reason” occurs.

Signature int dcpMgr::pendOnEvent (int reason, int timeout);

Arguments (IN) reason – See values in dcphca.h file timeout – Time in host operating system clock ticks to wait for event.


Returns 0 – Received the event -1 – Timeout expired, or invalid reason argument

Caveats None




Read ConfigurationMemory

dcpMgr::readCfgMemory()

Description Read the PCI configuration memory contents from the designated C-Port NP device’s config memory at a given address into a buffer provided by the calling routine.

Signature int dcpMgr::readCfgMemory(int *address, int *buffer, int count);

Arguments (IN) address – Address of the memory to be read. buffer – Pointer to the caller’s buffer to hold the results of the read operation. count – Length in bytes of the caller’s buffer referenced by buffer.



Caveats The calling routine is responsible to ensure that the buffer referenced by buffer is sufficient to contain the data read.

Implementation Notes This routine handles redirection of the obtained data to an actual NP device or to the C-Ware Simulator.



Read Memory dcpMgr::readMemory()

Description Read the memory contents from the designated C-Port NP device’s memory at a given address into the buffer space provided by the calling routine.

Signature int dcpMgr::readMemory (int *address, int *buffer, int count);

Arguments (IN) address – Address (in the NP internal address space) of the memory to be read. buffer – Pointer to the caller’s buffer to hold the results of the read operation. This pointer must be four-byte aligned. count – Length in bytes of the caller’s buffer referenced by buffer. This value must be a multiple of four.



Caveats None

Implementation Notes This routine handles redirection of the obtained data to an actual NP device or to the C-Ware Simulator. This routine performs no byte swapping.



Start DMA Transfer to Host dcpMgr::startDmaToHost()

Description Set up DMA registers to initiate a DMA transfer from a BMU buffer in the designated C-Port NP device to host memory.

Signature int dcpMgr::startDmaToHost (int pool, int btag, char *dstptr, int len);

Arguments (IN) pool – On the designated NP device, the BMU buffer pool from which to obtain the data. btag – BMU btag specifying the source buffer. dstptr – Pointer to a location in host memory to write data. len – Length in bytes of the calling routine’s buffer.


Returns 0 – Always returned

Caveats This routine assumes that there exists an outbound Base Address Register (BAR) on the NP that is already initialized to reference the destination buffer passed in by the caller. Calling routine is responsible for checking status on completion of the DMA transfer, using the dcpMgr::dmaToHostSenseDone() method.




Start DMA Transfer to NP dcpMgr::startDmaToDcp()

Write ConfigurationMemory

dcpMgr::writeCfgMemory()

Description Set up the DMA registers to initiate a DMA transfer from host memory to a BMU buffer in the designated C-Port NP device.

Signature int dcpMgr::startDmaToDcp (char *srcptr, int pool, int btag, int len);

Arguments (IN) srcptr – Pointer to a location in host memory to obtain data. pool – On the designated NP device, the BMU buffer pool into which to write the data. btag – BMU btag specifying the destination buffer. len – Length in bytes of the calling routine’s buffer.


Returns 0 – Always returned

Caveats Calling routine is responsible for checking status on completion of the DMA transfer, using the dcpMgr::dmaToDcpSenseDone() method.


Description Write the PCI configuration memory contents of the designated C-Port NP device’s config memory from a buffer provided by the calling routine.

Signature int dcpMgr::writeCfgMemory(int *address, int *buffer, int count);

Arguments (IN) address – Address of the PCI configuration memory to write to. buffer – Pointer to the caller’s buffer that holds the contents to write. count – Length in bytes of the caller’s buffer referenced by buffer.



Caveats The calling routine is responsible to ensure that the buffer referenced by buffer is sufficient to contain the data to be written.




Write Memory dcpMgr::writeMemory()

Description Write to the designated C-Port NP device’s memory at a given address from a buffer provided by the calling routine.

Signature int dcpMgr::writeMemory (int *address, int *buffer, int count);

Arguments (IN) address – Address (in the NP internal address space) of the memory to be written. buffer – Pointer to the caller’s buffer that holds the contents to be written. This pointer must be four-byte aligned. count – Length in bytes of the caller’s buffer referenced by buffer. This value must be a multiple of four.



Caveats This operation updates the current access pointer for the designated NP device.






CSTHAPG-UG/D

Rev 13

INDEX

BBase Address Registers (BARs)

byte ordering 143four-byte data transfers 142inbound address mapping conventions 145memory-mapped access 143outbound address mapping conventions 145purpose of 142

CC-5

base address registers (BARs) 142byte ordering 143four-byte data transfers 142inbound address mapping conventions 145memory-mapped access 143outbound address mapping conventions 145

mailbox registersasserting an interrupt 149clearing the interrupt vector 149executing the interrupt handler 149setting a vector in 148

C-5 data structuresper C-5 device

Host API management of 81C-5 Device Driver 27

comparison with previous drivers 140data transfer mechanisms 140dependencies among drivers and libraries 36functional overview 138high level public methods 150implementation of 139implemented by np.a library 36

interrupt functionality support 147C-5 interrupts to host processor 147host processor interrupts to C-5 148

overview 137PCI interface functionality 142programming

compared with Host API programming 30software deliverable 138

C-5 diagnostic software 27C-5 Switch Module board 29command specification file

for DCP Shell commands 45command specification language

for DCP Shell commands 45commands

DCP Shell 43config.h file 39console task 27control plane 25, 25

tasks 25cpiMgr data type 55C-Ware Development System (CDS)

building Linux Board Support Packages for 41building VxWorks Board Support Packages for 39C-5 Switch Module board for 29PIM boards for 29support for host application development 29

C-Ware Software Toolset (CST)location of host application software components 36support for host application development 26

CSTHAPG-UG/D REV 13

164 INDEX

Ddata plane 25, 25

tasks 25DCP Shell 27

command handler programming model 46command specification file 45command specification language 45implementing additional commands 43sample code for implementing commands 47support for dynamically linkable modules (DLM) 49

dcpAppInit() entry point 48dcpMgr class

dcpTable array 152high level public methods 150

dcpMgr.cpp file 150dcpTable array 152diagnostics

for the C-5 network processor 27dmaToDcpSenseDone() method 153dmaToHostSenseDone() method 153dshell utility 45

command handler programming model 46sample code 47

dynamically linkable modules (DLM)build the vxWorks image for standalong loader 50building and using 48coding a DLM 49invocation mechanism 49location of interface definitions 49support by the DCP Shell 49

Eentry point

for host application user code 48

FFile Transfer Protocol (FTP)

using, to load vxWorks image file 51forwarding path 25

CSTHAPG-UG/D REV 13

GGlobal Bus 61

Hhost API programming

execution model 53remote procedure calls 77, 81

Host API routines 27hsAllocPktBuf() 120hsAllocPktBufVec() 121hsClockCalibrate() 73hsClose() 114hsCloseDcp() 58hsClosePkt() 118hsClosePort() 115hsCloseProtocol() 62hsCpiFree() 56hsCpiInit() 57hsFlushProtocol() 62hsFreePktBuf() 120hsFreePktBufVec() 121hsGetDcpHandle() 58hsInit() 113hsOpen() 114hsOpenDcp() 59hsOpenPkt() 118hsOpenPort() 115hsOpenProtocol() 63hsPackageLoad() 73, 122hsPeekProtocol() 64hsPendOnEvent() 74hsPktClose() 68hsPktFree2() 68hsPktOpen() 69hsPktRead() 69hsPktRead2() 70hsPktSetBtag2() 70hsPktSetBuf2() 71hsPktSetDesc2() 71hsPktWrite() 72hsPktWrite2() 72hsPoll() 132


INDEX 165

hsQueryConfig() 74hsReadCfgMemory() 130hsReadLssi() 127hsReadMemory() 60, 129hsReadPkt() 119hsReadPort() 116hsReadProtocol() 65hsReadRegister() 131hsReset() 75, 128hsRpc() 124hsRpcProcReg() 125hsRpcProcUnreg() 125hsSeek() 60hsSignal() 75, 132hsSymbolImport() 76, 123hsWriteCfgMemory() 130hsWriteLssi() 128hsWriteMemory() 61, 129hsWritePkt() 119hsWritePort() 116hsWriteProtocol() 66hsWriteRegister() 131hsXpReqHndlrReg() 126hsXpReqHndlrUnreg() 127hsXpRequest() 126ksMdioRead() 81ksMdioReadComplete() 81ksMdioWrite() 81ksMdioWriteComplete() 81m5ChannelConfig0c1() 85m5ChannelConfig0c12c() 88m5ChannelConfig0c12cx4() 88m5ChannelConfig0c1x48() 86m5ChannelConfig0c3c() 87m5ChannelConfig0c3cx16() 87m5ChannelConfig0c48c() 89m5ChannelDisable() 90m5ChannelEnable() 91m5ChannelFifo() 91m5CheckFlowSchedTable() 89m5FifoChannel() 92m5GetStatus() 92m5Init() 84m5Open() 84m5SetEgressSequenceNo() 93


m5SetFlowSchedTable() 90m5SetMpsnTimeout() 93management of per-C-5 data 81programming

compared with C-5 Device Driver programming 30purpose of 54Table Services routines 77tsEntryDelete() 77tsEntryFindNext() 77tsEntryInsert() 77tsEntryLookup() 77tsEntryModify() 77tsTableCreate() 77tsTableInit() 77

Host API Table Servicesaccessed via sysSvcsHost.a library 41

host applicationdefined 25invoking from image file 48

host application developmentCDS support for 29CST support for 26setting up Linux for 27, 35setting up Tornado for 34system configurations 31

Host Application Module 27, 34, 35building software for 35

Host Application Module boardloading image file into 51

host application softwarelocation in CST of components 36

host processordefined 25

host-side C-Ware Debugger agent task 28hsAllocPktBuf() routine 120hsAllocPktBufVec() routine 121hsClockCalibrate() routine 73hsClose() routine 114hsCloseDcp() routine 58hsClosePkt() routine 118hsClosePort() routine 115hsCloseProtocol() routine 62hsCpiFree() routine 56

usage 82

CSTHAPG-UG/D REV 13

166 INDEX

hsCpiInit() routine 57usage 82

HsDcpHandle data type 55hsFlushProtocol() routine 62hsFreePktBuf() routine 120hsFreePktBufVec() routine 121hsGetDcpHandle() routine 58hsInit() routine 113hsOpen() routine 114hsOpenDcp() routine 59hsOpenPkt() routine 118hsOpenPort() routine 115hsOpenProtocol() routine 63hsPackageLoad() routine 73, 122hsPeekProtocol() routine 64hsPendOnEvent() routine 74hsPktClose() routine 68hsPktFree2() routine 68hsPktOpen() routine 69hsPktRead() routine 69hsPktRead2() routine 70hsPktSetBtag2() routine 70hsPktSetBuf2() routine 71hsPktSetDesc2() routine 71hsPktWrite() routine 72hsPktWrite2() routine 72hsPoll() routine 132HsProtocolHandle data type 55hsQueryConfig() routine 74hsReadCfgMemory() routine 130hsReadLssi() routine 127hsReadMemory() routine 60, 129hsReadPkt() routine 119hsReadPort() routine 116hsReadProtocol() routine 65hsReadRegister() routine 131hsReset() routine 75, 128hsRpc() routine 124hsRpcProcReg() routine 125hsRpcProcUnreg() routine 125hsSeek() routine 60hsSignal() routine 75, 132hsSymbolImport() routine 76, 123hsWriteCfgMemory() routine 130hsWriteLssi() routine 128

CSTHAPG-UG/D REV 13

hsWriteMemory() routine 61, 129hsWritePkt() routine 119hsWritePort() routine 116hsWriteProtocol() routine 66hsWriteRegister() routine 131hsXpReqHndlrReg() routine 126hsXpReqHndlrUnreg() routine 127hsXpRequest() routine 126

Iimage file

invoking host application program from 48loading into the CDS Host Application Module 51

interruptssupport for functionality in C-5 Device Driver 147

C-5 interrupts to host processor 147host processor interrupts to C-5 148

KksMdioRead() routine 81ksMdioReadComplete() routine 81ksMdioWrite() routine 81ksMdioWriteComplete() routine 81

LLinux

building Board Support Packages for CDS 41Linux development environment

setting up for CDS host application development 27, 35loadPackage() method 154

MM-5 API 83M-5 channel adapter 83m5ChannelConfig0c1() routine 85m5ChannelConfig0c12c() routine 88m5ChannelConfig0c12cx4() routine 88m5ChannelConfig0c1x48() routine 86m5ChannelConfig0c3c() routine 87m5ChannelConfig0c3cx16() routine 87


INDEX 167

m5ChannelConfig0c48c() routine 89m5ChannelDisable() routine 90m5ChannelEnable() routine 91m5ChannelFifo() routine 91m5CheckFlowSchedTable() routine 89m5FifoChannel() routine 92m5GetStatus() routine 92m5Init() routine 84m5Open() routine 84m5SetEgressSequenceNo() routine 93m5SetFlowSchedTable() routine 90m5SetMpsnTimeout() routine 93mailbox registers

asserting an interrupt 149clearing the interrupt vector 149executing the interrupt handler 149setting a vector in 148

memory referenceexample of C-5 reference in host processor memory 146example of host processor reference in C-5 memory 143

model of executionfor Host API routines 53

Motorola MCP750 single board computer 27, 29, 34, 35Motorola PowerPC microprocessor 29mv2600.h file 40

Nnetwork processor

defined 25np.a library 43

building in a Linux environment 39building VxWorks outside of Tornado development

environment 38dependencies among drivers and libraries 36implements the C-5 Device Driver 36

OOpen() method 155


PPCI interface functionality

in the C-5 Device Driver 142PCI read/write tasks 28pciAutoConfig.h file 40pendOnEvent() method 156Physical Interface Module (PIM) boards 29pipes 140PKT_BUF_HDR data type 55PKT_DESC data type 56printflistener task 28proxyRpc.c file 80

RRaven PCI bridge 139readCfgMemory() method 157readMemory() method 158remote procedure calls 77, 81

enabling for the C-5 80

Ssingle board computer (SBC)

Motorola MCP750 29standalone loader

for vxWorks 50startDmaToDcp() method 160startDmaToHost() method 159statically linked modules 47sysLib.c file 40sysSvcsHost.a library

implements Host API Table Services and Queue Services 41system configurations

for host application development 31

CSTHAPG-UG/D REV 13

168 INDEX

TTable Services routines

in Host API routines 77telnet session listener task 28Tornado development environment 35

project files for 26setting up for CDS host application development 34

tsEntryDelete() routine 77tsEntryFindNext() routine 77tsEntryInsert() routine 77tsEntryLookup() routine 77tsEntryModify() routine 77tsTableCreate() routine 77tsTableInit() routine 77

UUSER_LIBDIR environment variable 47USER_OBJECTS environment variable 47, 47

CSTHAPG-UG/D REV 13

VVxWorks

building Board Support Packages for CDS 39VxWorks image file 26

WwriteCfgMemory() method 152, 160writeMemory() method 161

XxpDisable() method 152xpEnable() method 154


CSTHAPG-UG/D

Rev 13, 9/2004

How to Reach Us:

USA/Europe/Locations not listed:Freescale Semiconductor Literature DistributionP.O. Box 5405, Denver, Colorado 802171-800-521-6274 or 480-768-2130

Japan:Freescale Semiconductor Japan Ltd.SPS, Technical Information Center3-20-1, Minami-AzabuMinato-kuTokyo 106-8573, Japan81-3-3440-3569

Asia/Pacific:Freescale Semiconductor H.K. Ltd.2 Dai King StreetTai Po Industrial EstateTai Po, N.T. Hong Kong852-26668334

Learn More:For more information about Freescale Semiconductor products, please visithttp://www.freescale.com

Information in this document is provided solely to enable system and software implementers to use

Freescale Semiconductor products. There are no express or implied copyright licenses granted

hereunder to design or fabricate any integrated circuits or integrated circuits based on the information

in this document.

Freescale Semiconductor reserves the right to make changes without further notice to any products

herein. Freescale Semiconductor makes no warranty, representation or guarantee regarding the

suitability of its products for any particular purpose, nor does Freescale Semiconductor assume any

liability arising out of the application or use of any product or circuit, and specifically disclaims any

and all liability, including without limitation consequential or incidental damages. “Typical” parameters

which may be provided in Freescale Semiconductor data sheets and/or specifications can and do

vary in different applications and actual performance may vary over time. All operating parameters,

including “Typicals” must be validated for each customer application by customer’s technical experts.

Freescale Semiconductor does not convey any license under its patent rights nor the rights of others.

Freescale Semiconductor products are not designed, intended, or authorized for use as components

in systems intended for surgical implant into the body, or other applications intended to support or

sustain life, or for any other application in which the failure of the Freescale Semiconductor product

could create a situation where personal injury or death may occur. Should Buyer purchase or use

Freescale Semiconductor products for any such unintended or unauthorized application, Buyer shall

indemnify and hold Freescale Semiconductor and its officers, employees, subsidiaries, affiliates, and

distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney

fees arising out of, directly or indirectly, any claim of personal injury or death associated with such

unintended or unauthorized use, even if such claim alleges that Freescale Semiconductor was

negligent regarding the design or manufacture of the part.

Freescale™ and the Freescale logo are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners.© Freescale Semiconductor, Inc. 2004.