View 2001693_964300.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

Spectra-4x155 (PM5316) Driver Manual
PM5316
SPECTRA-4X155 DEVICE DRIVER
DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL PRELIMINARY ISSUE 1: JANUARY, 2001
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
Spectra-4x155 (PM5316) Driver Manual
ABOUT THIS MANUAL AND SPECTRA-4X155
This manual describes the SPECTRA-4x155 (PM5316) device driver. It describes the driver's functions, data structures, and architecture. This manual focuses on the driver's interfaces and their relationship to your application, real-time operating system, and to the device. It also describes in general terms how to modify and port the driver to your software and hardware platform.
Audience
This manual was written for people who need to: * * * Evaluate and test the SPECTRA-4x155 devices Modify and add to the SPECTRA-4x155 driver's functions Port the SPECTRA-4x155 driver to a particular platform.
References
For more information about the SPECTRA-4x155 driver, see the driver's Release Notes.( PMC2001967) For more information about the SPECTRA-4x155 device, see the documents listed in Table 1 and any related errata documents. Table 1: Related Documents Document Number PMC-1990822 Document Name PM5316 SPECTRA-4X155 Telecom Standard Product Data Sheet
Note: Ensure that you use the document that PMC-Sierra issued for your version of the device and driver.
Revision History
Issue No. Issue 1 Issue Date January 2001 Details of Change Document created
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
2
Spectra-4x155 (PM5316) Driver Manual
Legal Issues
None of the information contained in this document constitutes an express or implied warranty by PMC-Sierra, Inc. as to the sufficiency, fitness or suitability for a particular purpose of any such information or the fitness, or suitability for a particular purpose, merchantability, performance, compatibility with other parts or systems, of any of the products of PMC-Sierra, Inc., or any portion thereof, referred to in this document. PMC-Sierra, Inc. expressly disclaims all representations and warranties of any kind regarding the contents or use of the information, including, but not limited to, express and implied warranties of accuracy, completeness, merchantability, fitness for a particular use, or non-infringement. In no event will PMC-Sierra, Inc. be liable for any direct, indirect, special, incidental or consequential damages, including, but not limited to, lost profits, lost business or lost data resulting from any use of or reliance upon the information, whether or not PMC-Sierra, Inc. has been advised of the possibility of such damage. The information is proprietary and confidential to PMC-Sierra, Inc., and for its customers' internal use. In any event, no part of this document may be reproduced in any form without the express written consent of PMC-Sierra, Inc. (c) 2001 PMC-Sierra, Inc. PMC-2001693 (P1), ref PMC-2000216 (P2)
Contacting PMC-Sierra
PMC-Sierra, Inc. 105-8555 Baxter Place Burnaby, BC Canada V5A 4V7 Tel: (604) 415-6000 Fax: (604) 415-6200 Document Information: document@pmc-sierra.com Corporate Information: info@pmc-sierra.com Technical Support: apps@pmc-sierra.com Web Site: http://www.pmc-sierra.com
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
3
Spectra-4x155 (PM5316) Driver Manual
TABLE OF CONTENTS
About this Manual and SPECTRA-4x155............................................................................2 Table of Contents.................................................................................................................4 List of Figures ....................................................................................................................10 List of Tables...................................................................................................................... 11 1 2 Introduction .................................................................................................................13 Driver Functions and Features....................................................................................14
2.1 General Driver Functions ............................................................................................14 Open / Close Driver Module .................................................................................14 Start / Stop Driver Module ....................................................................................14 Add / Delete Device..............................................................................................14 Device Initialization...............................................................................................14 Activate / De-Activate Device ...............................................................................15 Read / Write Device Registers .............................................................................15 Interrupt Servicing / Polling ..................................................................................15 Statistics Collection...............................................................................................15 2.2 SPECTRA-4x155 Specific Driver Functions ...............................................................15 Input / Output Interfaces.......................................................................................15 Section Overhead.................................................................................................16 Line Overhead ......................................................................................................16 Path Overhead .....................................................................................................16 Device Update ......................................................................................................17 Device Diagnostics ...............................................................................................17 Statistics and Alarm Monitoring ............................................................................17 Specific Callback Functions..................................................................................17 3 Software Architecture..................................................................................................18
3.1 Driver External Interfaces ...........................................................................................18 Application Programming Interface ......................................................................18 Real-Time OS Interface........................................................................................19 Hardware Interface ...............................................................................................19 3.2 Main Components .......................................................................................................19 Module Data-Block and Device(s) Data-Blocks ...................................................20 Interrupt-Service Routine .....................................................................................21 Deferred-Processing Routine ...............................................................................21 Alarms, Status and Statistics ................................................................................21 Input / Output........................................................................................................22 Section Overhead.................................................................................................22 Line Overhead ......................................................................................................22 Path Overhead .....................................................................................................22
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
4
Spectra-4x155 (PM5316) Driver Manual
3.3 Software States ...........................................................................................................23 Module States.......................................................................................................23 Device States........................................................................................................24 3.4 Processing Flows ........................................................................................................25 Module Management............................................................................................25 Device Management ............................................................................................26 3.5 Interrupt Servicing.......................................................................................................27 Calling spe4x155ISR ............................................................................................27 Calling spe4x155DPR ..........................................................................................28 Calling spe4x155Poll ............................................................................................29 4 Data Structures ...........................................................................................................30
4.1 Constants ....................................................................................................................30 4.2 Structures Passed by the Application .........................................................................30 Module Initialization Vector: MIV ..........................................................................30 Device Initialization Vector: DIV ...........................................................................31 ISR Enable/Disable Mask.....................................................................................35 Statistic Counters (CNT).......................................................................................40 Time-Slot structure: TSLOT..................................................................................42 PRBS Configuration Structure..............................................................................43 Device and Alarm Status ......................................................................................43 4.3 Structures in the Driver's Allocated Memory...............................................................47 Module Data Block: MDB .....................................................................................47 Device Data Block: DDB.......................................................................................48 4.4 Structures Passed through RTOS Buffers ..................................................................50 Interrupt-Service Vector: ISV................................................................................50 Deferred-Processing Vector: DPV........................................................................51 4.5 Global Variable............................................................................................................51 5 Application Programming Interface.............................................................................52
5.1 Module Management ..................................................................................................52 Opening the Driver Module: spe4x155ModuleOpen ............................................52 Closing the Driver Module: spe4x155ModuleClose .............................................53 Starting the Driver Module: spe4x155ModuleStart...............................................53 Stopping the Driver Module: spe4x155ModuleStop .............................................53 5.2 Profile Management....................................................................................................54 Setting an Initialization Profile: spe4x155SetInitProfile ........................................54 Getting an Initialization Profile: spe4x155GetInitProfile .......................................55 Deleting an Initialization Profile: spe4x155ClrInitProfile.......................................55 5.3 Device Management ...................................................................................................56 Adding a Device: spe4x155Add ...........................................................................56 Deleting a Device: spe4x155Delete .....................................................................56 Initializing a Device: spe4x155Init ........................................................................57
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
5
Spectra-4x155 (PM5316) Driver Manual
Updating the Configuration of a Device: spe4x155Update ..................................58 Resetting a Device: spe4x155Reset ....................................................................58 Activating a Device: spe4x155Activate ................................................................59 De-Activating a Device: spe4x155DeActivate......................................................59 5.4 Device Read and Write ...............................................................................................60 Reading from Device Registers: spe4x155Read .................................................60 Writing to Device Registers: spe4x155Write ........................................................60 Reading from a block of Device Registers: spe4x155ReadBlock........................61 Writing to a Block of Device Registers: spe4x155WriteBlock ..............................62 5.5 Input Output ................................................................................................................62 Sending Line AIS Maintenance Signal: spe4x155RINGLineAISControl ..............62 Sending Line RDI Maintenance Signal: spe4x155RINGLineRDIControl .............63 Creating a Timeslot Mapping: spe4x155IOMapSlot.............................................63 Determining if a Timeslot is being Multicasted: spe4x155IOIsMulticast ..............64 Getting Destination Timeslot(s): spe4x155IOGetDestSlot ...................................64 Getting Source Timeslot: spe4x155IOGetSrcSlot ................................................65 5.6 Section Overhead .......................................................................................................66 Terminating Section Overhead: spe4x155SOHTermination.................................66 Reading and Setting the Section Trace Message (J0): spe4x155SectionTraceMsg ..........................................................................66 Writing the Z0 Byte: spe4x155SOHWriteZ0.........................................................67 Forcing Out-of-Frame: spe4x155SOHDiagOOF ..................................................68 Forcing Errors in the Framing Bytes: spe4x155SOHDiagFB...............................68 Forcing Section BIP-8 Errors: spe4x155SOHDiagB1 ..........................................69 Forcing Loss-of-Signal: spe4x155SOHDiagLOS .................................................69 5.7 Line Overhead ............................................................................................................70 Terminating Line Overhead: spe4x155LOHTermination ......................................70 Reading the Received K1 and K2 Bytes: spe4x155LOHReadK1K2 ...................71 Writing the Transmitted K1 and K2 Bytes: spe4x155LOHWriteK1K2 ..................71 Reading the S1 Byte: spe4x155LOHReadS1 ......................................................72 Writing the S1 Byte: spe4x155LOHWriteS1.........................................................72 Inserting Line Remote Defect Indication: spe4x155LOHInsertLineRDI ...............73 Forcing Line BIP-8 Errors: spe4x155LOHDiagB2................................................73 Inserting Line AIS: spe4x155LOHInsertLineAIS ..................................................74 Configuring Signal Fail and Signal Degrade: spe4x155LOHCfgSFSD................74 5.8 Path Overhead............................................................................................................75 Path Trace Message.............................................................................................75 Retrieving and Setting the Path Trace Messages: spe4x155PathTraceMsg.......75 Receive Path Overhead (RPOH) .........................................................................76 Terminating Receive Path Overhead: spe4x155RPOHTermination.....................76 Path Signal Label: spe4x155RPOHPathSignalLabel..........................................76 Forcing Loss-of-Pointer: spe4x155RPOHDiagLOP .............................................77 Forcing Pointer Justification: spe4x155RPOHDiagPJ .........................................77 Forcing Errors in the H4 Byte: spe4x155RPOHDiagH4.......................................78 Forcing Tributary Path AIS: spe4x155RPOHInsertTUAIS....................................79 Forcing Path AIS: spe4x155RPOHInsertPAIS .....................................................79 Transmit Path Overhead (TPOH) .........................................................................80 Terminating Transmit Path Overhead: spe4x155TPOHTermination ....................80
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
6
Spectra-4x155 (PM5316) Driver Manual
Forcing Path BIP-8 Errors: spe4x155TPOHDiagB3.............................................80 Forcing a Pointer Value: spe4x155TPOHForceTxPtr ..........................................81 Writing the New Data Flag Bits: spe4x155TPOHInsertNDF ................................82 Writing the J1 Byte: spe4x155TPOHWriteJ1 .......................................................82 Writing the C2 Byte: spe4x155TPOHWriteC2......................................................83 Writing the Path Remote Error Indication Count: spe4x155TPOHInsertPREI.....83 Writing the F2 Byte: spe4x155TPOHWriteF2.......................................................84 Writing the Z3 Byte: spe4x155TPOHWriteZ3.......................................................84 Writing the Z4 Byte: spe4x155TPOHWriteZ4.......................................................85 Writing the N1/Z5 Byte: spe4x155TPOHWriteZ5 .................................................85 Controlling Pointer Justification: spe4x155TPOHDiagPJ.....................................86 Forcing Multiframe Error: spe4x155TPOHDiagH4...............................................86 Forcing Tributary Path AIS: spe4x155TPOHInsertTUAIS ....................................87 Forcing Path AIS: spe4x155TPOHInsertPAIS......................................................87 5.9 DROP / ADD Bus PRBS Generator and Monitor (DPGM / APGM) ............................88 DROP Bus PRBS Generator and Monitor (DPGM) .............................................88 Configuring the PRBS Generator: spe4x155DPGMGenCfg................................88 Configuring the PRBS Monitor: spe4x155DPGMMonCfg ....................................89 Forcing Generation of a New PRBS: spe4x155DPGMGenRegen ......................89 Forcing Bit Errors: spe4x155DPGMGenForceErr ................................................90 Forcing a Resynchronization: spe4x155DPGMMonResync ................................90 ADD Bus PRBS Generator and Monitor (APGM) ................................................91 Configuring the PRBS Generator: spe4x155APGMGenCfg ................................91 Configuring the PRBS Monitor: spe4x155APGMMonCfg ....................................91 Forcing Generation of a New PRBS: spe4x155APGMGenRegen.......................92 Forcing Bit Errors: spe4x155APGMGenForceErr ................................................92 Forcing a Resynchronization: spe4x155APGMMonResync ................................93 5.10 Interrupt Service Functions......................................................................................93 Configuring ISR Processing: spe4x155ISRConfig ...............................................93 Getting the Interrupt Status Mask: spe4x155GetMask ........................................94 Setting the Interrupt Enable Mask: spe4x155SetMask ........................................94 Clearing the Interrupt Enable Mask: spe4x155ClearMask...................................95 Polling the Interrupt Status Registers: spe4x155Poll ...........................................95 Interrupt-Service Routine: spe4x155ISR..............................................................96 Deferred-Processing Routine: spe4x155DPR......................................................96 Setting the Thresholds for Callbacks: spe4x155SetThresh .................................97 Getting the Thresholds for Callbacks: spe4x155GetThresh ................................97 Getting the Event Counters: spe4x155GetThreshCntr ........................................98 5.11 Alarm, Status and Statistics Functions ....................................................................98 Configuring the Device Statistics: spe4x155CfgStats ..........................................98 Statistics Collection Routine: spe4x155GetCnt....................................................99 Getting Counter for SOH Block: spe4x155GetCntSOH .......................................99 Getting Counters for LOH Block: spe4x155GetCntLOH ....................................100 Getting Counters for RPOH Block: spe4x155GetCntRPOH ..............................100 Getting Counters for TPOH Block: spe4x155GetCntTPOH ...............................101 Getting Counters for Pointer Justifications: spe4x155GetCntPJ .......................101 Getting Current Status: spe4x155GetStatus ......................................................102 Getting Current Status for IO block: spe4x155GetStatusIO ...............................102 Getting Current Alarm Status for SOH block: spe4x155GetStatusSOH.............103 Getting Current Alarm Status for LOH block: spe4x155GetStatusLOH .............103
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
7
Spectra-4x155 (PM5316) Driver Manual
Getting Current Alarm Status for RPOH block: spe4x155GetStatusRPOH .......104 Getting Current Alarm Status for TPOH block: spe4x155GetStatusTPOH ........104 5.12 Device Diagnostics ................................................................................................105 Testing Register Accesses: spe4x155DiagTestReg ...........................................105 Clearing and Setting a Line Loopback: spe4x155DiagLineLoop .......................105 Clearing and Setting a Serial Loopback: spe4x155DiagSerialLoop ..................106 Clearing and Setting a Parallel Loopback: spe4x155DiagParaLoop .................106 Clearing and Setting a System-Side Loopback: spe4x155DiagSysSideLineLoop.................................................................107 5.13 Callback Functions ................................................................................................107 Notifying the Application of IO Events: cbackSpe4x155IO.................................108 Notifying the Application of SOH Events: cbackSpe4x155SOH.........................108 Notifying the Application of LOH Events: cbackSpe4x155LOH .........................109 Notifying the Application of RPOH Events: cbackSpe4x155RPOH ...................109 Notifying the Application of TPOH Events: cbackSpe4x155TPOH .................... 110 Notifying the Application of DPGM Events: cbackSpe4x155DPGM................... 110 Notifying the Application of APGM Events: cbackSpe4x155APGM ................... 111 6 Hardware Interface ................................................................................................... 112
6.1 Device I/O ................................................................................................................. 112 Reading from a Device Register: sysSpe4x155Read ........................................ 112 Writing to a Device Register: sysSpe4x155Write............................................... 112 Polling a Bit: sysSpe4x155PollBit....................................................................... 113 6.2 System-Specific Interrupt Servicing .......................................................................... 113 Installing the ISR Handler: sysSpe4x155ISRHandlerInstall ............................... 114 ISR Handler: sysSpe4x155ISRHandler.............................................................. 114 Removing the ISR Handler: sysSpe4x155ISRHandlerRemove......................... 115 7 RTOS Interface ......................................................................................................... 116
7.1 Memory Allocation / De-Allocation ............................................................................ 116 Allocating Memory: sysSpe4x155MemAlloc ...................................................... 116 Freeing Memory: sysSpe4x155MemFree .......................................................... 116 Copying Memory: sysSpe4x155MemCpy .......................................................... 117 Setting Memory: sysSpe4x155MemSet ............................................................. 117 7.2 Buffer Management .................................................................................................. 117 Starting Buffer Management: sysSpe4x155BufferStart ...................................... 118 Getting an ISV Buffer: sysSpe4x155ISVBufferGet............................................. 118 Returning an ISV Buffer: sysSpe4x155ISVBufferRtn......................................... 118 Getting a DPV Buffer: sysSpe4x155DPVBufferGet ........................................... 119 Returning a DPV Buffer: sysSpe4x155DPVBufferRtn........................................ 119 Stopping Buffer Management: sysSpe4x155BufferStop .................................... 119 7.3 Timers .......................................................................................................................120 Sleeping a Task: sysSpe4x155TimerSleep ........................................................120 7.4 Preemption................................................................................................................120 Disabling Preemption: sysSpe4x155PreemptDisable ........................................120
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
8
Spectra-4x155 (PM5316) Driver Manual
Re-Enabling Preemption: sysSpe4x155PreemptEnable....................................121 7.5 System-Specific DPR Routine ..................................................................................121 DPR Task: sysSpe4x155DPRTask .....................................................................121 8 Porting the SPECTRA-4x155 Driver .........................................................................123
8.1 Driver Source Files ...................................................................................................123 8.2 Driver Porting Procedures.........................................................................................124 Step 1: Porting the RTOS interface ....................................................................124 Step 2: Porting the Hardware Interface ..............................................................126 Step 3: Porting the Application-Specific Elements..............................................127 Step 4: Building the Driver..................................................................................128 Appendix A: Coding Conventions....................................................................................129 Macros................................................................................................................130 Constants............................................................................................................130 Structures ...........................................................................................................130 Functions ............................................................................................................131 Variables .............................................................................................................131 API Files .............................................................................................................132 Hardware Dependent Files.................................................................................132 Other Driver Files ...............................................................................................133 Appendix B: Driver Return Codes ...................................................................................134 Appendix C: Events .........................................................................................................135 List of Terms ....................................................................................................................142 Acronyms.........................................................................................................................143 Index ................................................................................................................................144
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
9
Spectra-4x155 (PM5316) Driver Manual
LIST OF FIGURES
Figure 1: Driver External Interfaces...................................................................................18 Figure 2: Driver Architecture .............................................................................................20 Figure 3: Driver Software States .......................................................................................23 Figure 4: Module Management Flow Diagram ..................................................................25 Figure 5: Device Management Flow Diagram ...................................................................26 Figure 6: Interrupt Service Model ......................................................................................27 Figure 7: Polling Service Model.........................................................................................29
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
10
Spectra-4x155 (PM5316) Driver Manual
LIST OF TABLES
Table 1: SPECTRA-4x155 Module Initialization Vector: sSPE4X155_MIV ......................31 Table 2: SPECTRA-4x155 Device Initialization Vector: sSPE4X155_DIV .......................31 Table 3: Clock Config: sSPE4X155_CFG_CLK................................................................33 Table 4: Counters Config: sSPE4X155_CFG_SFSD........................................................33 Table 5: SPECTRA-4x155 Statistic Counters: sSPE4X155_CFG_CNT ..........................34 Table 6: SPECTRA-4x155 ISR Mask: sSPE4X155_MASK ..............................................35 Table 7: SPECTRA-4x155 Statistic Counters: sSPE4X155_STAT_CNT.........................40 Table 8: SPECTRA-4x155 Section Overhead Statistics Counters: sSPE4X155_STAT_CNT_SOH.................................................................................41 Table 9: SPECTRA-4x155 Line Overhead Status: sSPE4X155_STAT_CNT_LOH.........41 Table 10: SPECTRA-4x155 Path Processing Statistics Counters: sSPE4X155_STAT_CNT_RPOH ..............................................................................41 Table 11: SPECTRA-4x155 Transmit Path Processing Statistics Counters: sSPE4X155_STAT_CNT_TPOH ..............................................................................42 Table 12: SPECTRA-4x155 Pointer Justification Statistics Counters: sSPE4X155_STAT_CNT_PJ ....................................................................................42 Table 13: SPECTRA-4x155 Time-Slot: sSPE4X155_TSLOT...........................................42 Table 14: SPECTRA-4x155 PRBS Configuration: sSPE4X155_CFG_PRBS ..................43 Table 15: SPECTRA-4x155 Alarm Status: sSPE4X155_STATUS...................................43 Table 16: SPECTRA-4x155 Input / Output Alarm Status: sSPE4X155_STATUS_IO ......44 Table 17: SPECTRA-4x155 Section Overhead Alarm Status: sSPE4X155_STATUS_SOH .....................................................................................44 Table 18: SPECTRA-4x155 Line Overhead Status: sSPE4X155_STATUS_LOH ...........45 Table 19: SPECTRA-4x155 Receive Path Processing Alarm Status: sSPE4X155_STATUS_RPOH ..................................................................................45 Table 20: SPECTRA-4x155 Transmit Path Processing Alarm Status: sSPE4X155_STATUS_TPOH...................................................................................46 Table 21: SPECTRA-4x155 Module Data Block: sSPE4X155_MDB ...............................47
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
11
Spectra-4x155 (PM5316) Driver Manual
Table 22: SPECTRA-4x155 Device Data Block: sSPE4X155_DDB.................................48 Table 23: SPECTRA-4x155 Interrupt-Service Vector: sSPE4X155_ISV..........................50 Table 24: SPECTRA-4x155 Deferred-Processing Vector: sSPE4X155_DPV..................51 Table 25: Variable Type Definitions ................................................................................129 Table 26: Naming Conventions .......................................................................................129 Table 27: File Naming Conventions ................................................................................132 Table 28: Return Codes ..................................................................................................134 Table 29: SPECTRA-4x155 Events for IO callbacks ......................................................135 Table 30: SPECTRA-4x155 Events for SOH callbacks ..................................................135 Table 31: SPECTRA-4x155 Events for LOH callbacks...................................................136 Table 32: SPECTRA-4x155 Events for RPOH callback..................................................136 Table 33: SPECTRA-4x155 Events for TPOH callback ..................................................138 Table 34: SPECTRA-4x155 Events for DPGM callback .................................................140 Table 35: SPECTRA-4x155 Events for APGM callback ................................................140 Table 36: SPECTRA-4x155 Event Cause Values...........................................................140
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
12
Spectra-4x155 (PM5316) Driver Manual Introduction
1
INTRODUCTION
The following sections of the SPECTRA-4x155 Driver Manual describe the SPECTRA-4x155 device driver. The code provided throughout this document is written in the C language. This has been done to promote greater driver portability to other embedded hardware (Section 6) and RealTime Operating System environments (Section 7). Section 3 of this document, Software Architecture, defines the software architecture of the SPECTRA-4x155 device driver by including a discussion of the driver's external interfaces and its main components. The Data Structure information in Section 4 describes the elements of the driver that either configure or control its behavior. Included here are the constants, variables, and structures that the SPECTRA-4x155 device driver uses to store initialization, configuration, and status information. Section 5 provides a detailed description of each function that is a member of the SPECTRA-4x155 driver Application Programming Interface (API). This section outlines: (1) function calls that hide device-specific details and (2) application callbacks that notify the user of significant device events. For your convenience, Section 8 of this manual provides a brief guide to porting the SPECTRA4x155 device driver to your hardware and RTOS platform. In addition, an extensive Appendix (page 129) and Index (page 144) provides you with useful reference information.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
13
Spectra-4x155 (PM5316) Driver Manual Driver Functions and Features
2
DRIVER FUNCTIONS AND FEATURES
This section describes the main functions and features supported by the SPECTRA-4x155 driver.
2.1
General Driver Functions
Open / Close Driver Module
Opening the driver module allocates all the memory needed by the driver and initializes all module level data structures. Closing the driver module shuts down the driver module gracefully after deleting all devices that are currently registered with the driver, and releases all the memory allocated by the driver.
Start / Stop Driver Module
Starting the driver module involves allocating all Real-Time Operating System (RTOS) resources needed by the driver, such as timers, as well as installing the Interrupt-Service Routine (ISR) and spawning the Deferred-Processing Routine (DPR) task (except for memory, which is allocated during the Open call). Closing the driver module involves de-allocating all RTOS resources allocated by the driver without changing the amount of memory allocated to it.
Add / Delete Device
Adding a device involves verifying that the device exists, associating a device handle to the device, and storing context information about it. The driver uses this context information to control and monitor the device. Deleting a device involves shutting down the device and clearing the memory used for storing context information about this device.
Device Initialization
The initialization function resets then initializes the device and any associated context information about it. The driver uses this context information to control and monitor the SPECTRA-4x155 device.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
14
Spectra-4x155 (PM5316) Driver Manual Driver Functions and Features
Activate / De-Activate Device
Activating a device puts it into its normal mode of operation by enabling interrupts and other global registers. A successful device activation also enables other Application Programming Interface (API) invocations. De-activating a device removes it from its operating state, disables interrupts and other global registers.
Read / Write Device Registers
These functions provide a `raw' interface to the device. Device registers that are both directly and indirectly accessible are available for both inspection and modification via these functions. If applicable, block reads and writes are also available.
Interrupt Servicing / Polling
Interrupt Servicing is an optional feature. The user can disable device interrupts and instead poll the device periodically to monitor status and check for alarm/error conditions. Both polling and interrupt driven approaches detect a change in device status and report the status to a Deferred-Processing Routine (DPR). The DPR then invokes application callback functions based on the status information retrieved. This allows the driver to report significant events that occur within the device to the application.
Statistics Collection
Functions are provided to retrieve a snapshot of the various counts that are accumulated by the SPECTRA-4x155 device.
2.2
SPECTRA-4x155 Specific Driver Functions
These functions provide control and monitoring of the various sections of the SPECTRA-4x155 device. These device sections are generally enabled or disabled and configured by the mode specified during device initialization. Changes to device registers that would violate the characteristics of the initialized mode should be disallowed in application software.
Input / Output Interfaces
Functions will be provided to configure the following Input / Output interfaces: * * * Configuration of the RCLK, TCLK, PGMRCLK, and PGMTCLK clocks. System side telecom ADD/DROP bus and timeslot interchange (TSI) Ring control port activation and alarm insertion.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
15
Spectra-4x155 (PM5316) Driver Manual Driver Functions and Features
*
STS-3 or STS-3c mode on a per-155Mbps channel basis.
Section Overhead
The following functions will be provided to control the Section Overhead (SOH) processing: * * * * Enable/Disable section overhead termination Read/write the section trace message (J0). Read/reset the SOH BIP-8 error counter (B1). Detect and report the following alarm conditions: loss of frame (LOF), out of frame (OOF), loss of signal (LOS), trace identifier unstable (TIU), and trace identifier mismatch (TIM).
Line Overhead
The following functions will be provided to configure and monitor the Line Overhead processing: * * * * * * * * * * Enable/Disable line overhead termination Read/write the automatic protection switch (APS) bytes (K1,K2) Read/reset the LOH BIP-8 error counter (B2). Control automatic line alarm indication signal (AIS) insertion. Control the automatic insertion of remote error indications (REI) into the Z2 byte. Read/reset the incoming LOH REI counter (Z2). Control remote defect indication (RDI) transmission. Read the received synchronization byte (Z1). Configure signal fail (SF) and signal degrade (SD) accumulation period and threshold parameters. Detect and report LRDI, LAIS, APS, SF, and SD errors.
Path Overhead
The following functions will be provided to configure and monitor the Path Overhead processing: * * * * * * Enable/Disable path overhead termination Read/write the path trace message (J1). Read/write the path signal label (C2). Read/reset the BIP-8 error counter (B3). Detects and reports Loss of Pointer (LOP), loss of tributary multiframe (LOM), path alarm indication signal (PAIS), and path remote defect indication (RDI). Control automatic insertion of PAIS and RDI into the transmit stream.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
16
Spectra-4x155 (PM5316) Driver Manual Driver Functions and Features
* * *
Control automatic insertion of the remote error indication (REI) count into the path status byte (G1). Read the tandem connection maintenance byte (Z5). PRBS generation and monitoring.
Device Update
A function is provided to update the device's configuration without forcing a hardware reset.
Device Diagnostics
Functions to perform device diagnostics. * * * * * Device register read/write test. Line side diagnostic loopback between the receive and transmit clock and data interfaces. Parallel diagnostic loopback (between RSOP and TSOP blocks). Serial diagnostic loopback (between RXD+/- and TXD +/-). System side telecom bus interface loopback on an STS-1 basis.
Statistics and Alarm Monitoring
Functions to gather statistics and do alarm monitoring. * * * Retrieve a snapshot of the various overhead bytes. Retrieve a snapshot of the current alarm status for the various SONET/SDH alarms. Read/clear the accumulated error counts.
Specific Callback Functions
Callback functions are available to the application for event notification from the device driver. Application will be notified via the callback functions for selected events of interest such as: * * * * Detection of I/O alarm conditions. Detection of Section Overhead alarm conditions. Detection of Line Overhead alarm conditions. Detection of Path Overhead alarm conditions.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
17
Spectra-4x155 (PM5316) Driver Manual Software Architecture
3
SOFTWARE ARCHITECTURE
This section describes the software architecture of the SPECTRA-4x155 device driver. This includes a discussion of the driver's external interfaces and its main components.
3.1 Driver External Interfaces
Figure 1 illustrates the external interfaces defined for the SPECTRA-4x155 device driver. Figure 1: Driver External Interfaces
Application
Function Calls
Application Callbacks
Service Callbacks
SPECTRA-4x155 Device Driver
RTOS
Service Calls
Hardware Interrupts
Register Accesses
SPECTRA-4x155 Devices
Application Programming Interface
The driver Application Programming Interface (API) is a list of high-level functions that can be invoked by application programmers to configure, control and monitor SPECTRA-4x155 devices. The API functions perform operations that are more meaningful from a system's perspective. The API includes functions that: * Initialize the device(s)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
18
Spectra-4x155 (PM5316) Driver Manual Software Architecture
* * *
Perform diagnostic tests Validate configuration information Retrieve status and statistics information.
The driver API functions use the services of the other driver components to provide this systemlevel functionality to the application programmer. The driver API also consists of callback routines that are used to notify the application of significant events that take place within the device(s) and module.
Real-Time OS Interface
The driver's Real-Time Operating System (RTOS) interface provides functions that let the driver use RTOS services. The driver requires the memory, interrupt, and preemption services from the RTOS. The RTOS interface functions perform the following tasks for the driver: * * * Allocate and de-allocate memory Manage buffers for the Interrupt-Service Routine (ISR) and the Deferred-Processing Routine (DPR) Enable and disable preemption
The RTOS interface also includes service callbacks. These are functions installed by the driver using RTOS service calls such as installing interrupts. These service callbacks are invoked when an interrupt occurs. Note: You must modify RTOS interface code to suit your RTOS.
Hardware Interface
The hardware interface provides functions that read from and write to the device registers. The hardware interface also provides a template for an ISR that the driver calls when the device raises a hardware interrupt. You must modify this function based on the interrupt configuration of your system.
3.2 Main Components
Figure 2 illustrates the top-level architectural components of the SPECTRA-4x155 device driver. This applies in both polled and interrupt driven operation. In polled operation the ISR is called periodically. In interrupt operation the interrupt directly triggers the ISR. The driver includes eight main components: * * Module and device(s) data-blocks Interrupt-Service Routine
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
19
Spectra-4x155 (PM5316) Driver Manual Software Architecture
* * * * * *
Deferred-Processing Routine Alarm, status and statistics Input / Output Section Overhead Line Overhead Path Overhead
Figure 2: Driver Architecture
Application Function Calls Driver API Service Callbacks Input / Output Line Overhead RTOS Interface Path Overhead Register Accesses SPECTRA-4x155 Devices Service Calls RTOS Section Overhead Interrupt Context Module Data Block Device Data Blocks Interrupt Service Routine ....... Application Callbacks
Deferred Processing Routine
Alarm, Status & Statistics
Hardware Interface Hardware Interrupts
Module Data-Block and Device(s) Data-Blocks
The Module Data-Block (MDB) is the top layer data structure, created by the SPECTRA-4x155 driver to store context information about the driver module, such as: * * * Module state Maximum number of devices The DDB(s)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
20
Spectra-4x155 (PM5316) Driver Manual Software Architecture
The Device Data-Block (DDB) is contained in the MDB, and initialized by the driver module for each SPECTRA-4x155 device that is registered. There is one DDB per device and there is a limit on the number of DDBs, and that limit is set by the user when the module is initialized. The DDB is used to store context information about one device, such as: * * * * Device state Control information Initialization parameters Callback function pointers
Interrupt-Service Routine
The SPECTRA-4x155 driver provides an ISR called spe4x155ISR that checks if there is any valid interrupt condition present for the device. This function can be used by a system-specific interrupt-handler function to service interrupts raised by the device. The low-level interrupt-handler function that traps the hardware interrupt and calls spe4x155ISR is system and RTOS dependent. Therefore, it is outside the scope of the driver. Example implementations of an interrupt handler and functions that install and remove it are provided as a reference in section 6.2. You can customize these example implementations to suit your specific needs. See section 3.5 for a detailed explanation of the ISR and interrupt-servicing model.
Deferred-Processing Routine
The SPECTRA-4x155 driver provides a DPR called spe4x155DPR that processes any interrupt condition gathered by the ISR for that device. Typically, a system specific function, which runs as a separate task within the RTOS, will call spe4x155DPR. Example implementations of a DPR task and functions that install and remove it are provided as a reference in section 7.5. You can customize these example implementations to suit your specific needs. See section 3.5 for a detailed explanation of the DPR and interrupt-servicing model.
Alarms, Status and Statistics
The alarm, status and statistics component is responsible for monitoring alarms, tracking devices status information and retrieving statistical counts for each device registered with (added to) the driver.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
21
Spectra-4x155 (PM5316) Driver Manual Software Architecture
Input / Output
The Input / Output component is responsible for configuring the line side and system side device interfaces. On the line-side, functions are provided to control the four 155Mbps clock and data interfaces and ring control port. On the system-side, functions are provided to control the Add/Drop Telecom Bus data interfaces and the Time-Slot Interchange (TSI). As well, this component configures STS-3 or STS-3c mode for each of the four channels and reports mismatches between incoming STS-3/STS-3c streams and the channel configuration.
Section Overhead
The Section Overhead component provides functions to control and monitor the Section Overhead processing for each STS-3 stream. Read/Write access is given to the section trace message (J0). This message is compared with a configurable reference and mismatches are reported. As well, section BIP-8 (B1) errors are accumulated in a counter that can be read and cleared. Section Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Section Overhead bytes.
Line Overhead
The Line Overhead component is responsible for configuring and monitoring the Line Overhead on both receive and transmit sides for each STS-3. Read/write access is given to the APS bytes (K1 and K2) and most of the other overhead bytes. Line BIP-8 (B2) errors and REI indications are accumulated in counters that can be read and cleared. Line Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Line Overhead bytes. Additional functions are provided to configure the device to automatically insert line RDI and AIS.
Path Overhead
The Path Overhead component configures and monitors the Path Overhead on both receive and transmit sides for each STS-3. Read/write access is given to the path trace message (J1) and the path signal label (C2). Both are compared with a configurable reference and mismatches are reported. Path BIP-8 (B3) errors and REI are accumulated in a counter that can be read and cleared. Path Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Path Overhead bytes. Additional functions are provided to configure the device to automatically insert path RDI, path enhanced RSI, and path AIS.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
22
Spectra-4x155 (PM5316) Driver Manual Software Architecture
3.3 Software States
Figure 3 shows the software state diagram for the SPECTRA-4x155 driver. State transitions occur on the successful execution of the corresponding transition functions shown. State information helps maintain the integrity of the MDB and DDB(s) by controlling the set of operations allowed in each state. Figure 3: Driver Software States
spe4x155ModuleOpen Idle spe4x155ModuleClose Start
spe4x155ModuleStop
spe4x155ModuleStart
spe4x155ModuleClose
Ready
MODULE STATES
Start
spe4x155Add
spe4x155Delete
Present spe4x155Reset spe4x155Init spe4x155Activate Inactive spe4x155DeActivate PER-DEVICE STATES Active spe4x155Reset
Module States
The following is a description of the SPECTRA-4x155 module states. See section 5.1 for a detailed description of the API functions that are used to change the module state.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
23
Spectra-4x155 (PM5316) Driver Manual Software Architecture
Start The driver module has not been initialized. In this state the driver does not hold any RTOS resources (memory, timers, etc); it has no running tasks and performs no actions. Idle The driver module has been initialized successfully. The Module Initialization Vector (MIV) has been validated, the Module Data Block (MDB) has been allocated and loaded with current data, the per-device data structures have been allocated, and the RTOS has responded without error to all the requests sent to it by the driver. Ready This is the normal operating state for the driver module. This means that all RTOS resources have been allocated and the driver is ready for devices to be added. The driver module remains in this state while devices are in operation.
Device States
The following is a description of the SPECTRA-4x155 per-device states. The state that is mentioned here is the software state as maintained by the driver, and not as maintained inside the device itself. See section 5.3 for a detailed description of the API functions that are used to change the per-device state. Start The device has not been initialized. In this state the device is unknown by the driver and performs no actions. There is a separate flow for each device that can be added and they all start here. Present The device has been successfully added. A Device Data Block (DDB) has been associated to the device and updated with the user context and a device handle has been given to the user. In this state, the device performs no actions. Inactive In this state the device is configured but all data functions are de-activated including interrupts and alarms, status and statistics functions. Active This is the normal operating state for the device. In this state, interrupt servicing or polling is enabled.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
24
Spectra-4x155 (PM5316) Driver Manual Software Architecture
3.4
Processing Flows
This section describes the main processing flows of the SPECTRA-4x155 driver components. The flow diagrams below illustrate the sequence of operations that take place for different driver functions. The diagrams also serve as a guide to the application programmer by illustrating the sequence in which the application must invoke the driver API.
Module Management
The following diagram illustrates the typical function call sequences that occur when initializing or shutting down the SPECTRA-4x155 driver module. Figure 4: Module Management Flow Diagram
START Performs module level initialization of the driver. Validates the Module Initialization Vector (MIV). Allocates memory for the MDB and all its components (i.e. all the memory needed by the driver) and then initializes the contents of the MDB with the validated MIV. Performs module level startup of the driver. This involves allocating RTOS resources such as semaphores and timers and installing the ISR handler and DPR task. Register an initialization profile. This allows the user to store pre-defined parameter vectors that are validated ahead of time. When the deviceinitialization function is invoked only a profile number need to be passed. This method simplifies and expedites the above operations. Perform all device level functions here (add, init, activate, de-activate, reset, delete...) spe4x155ClrInitProfile De-register an initialization profile previously registered with the driver.
spe4x155ModuleOpen
spe4x155ModuleStart
spe4x155SetInitProfile
spe4x155ModuleStop
Performs Module level shutdown of the driver. This involves deleting all devices currently installed and de-allocating all timers and semaphores as well as removing the ISR handler and DPR task.
spe4x155ModuleClose
Performs module level shutdown of the driver. De-allocates all the driver's memory.
END
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
25
Spectra-4x155 (PM5316) Driver Manual Software Architecture
Device Management
The following figure shows the typical function call sequences that the driver uses to add, initialize, re-initialize, and delete the SPECTRA-4x155 device. Figure 5: Device Management Flow Diagram
START
spe4x155Add
Detects the new device in hardware, assigns a DDB to the new device and stores the user's context for the device. Returns a device handle to the user. Applies a reset to the device and initializes the device registers and associated RAMs based on the DIV passed by the user. The user may only pass a profile number, which corresponds to a previously saved & validated set of configurations (by using spe4x155SetInitProfile).
spe4x155Init
spe4x155Activate
Prepares the device for normal operation by enabling interrupts and other global enables. ISR routines are installed when the module is started using sysSpe4x155ISRHandlerInstall. The device is now operational and all other API can be invoked.
spe4x155Reset
In order to re-initialize the device, reset the device using spe4x155Reset and go through the initialization sequence again.
spe4x155DeActivate
De-activates the device and removes it from normal operation. This involves disabling the device interrupts. ISR routines for this device are removed using sysSpe4x155ISRHandlerRemove when the module is closed. Applies a software reset to the device to put it in its default startup state.
spe4x155Reset
spe4x155Delete
Removes the device from the list of devices being controlled by the SPECTRA-4x155 driver. This function de-allocates the device context information for the device being deleted.
END
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
26
Spectra-4x155 (PM5316) Driver Manual Software Architecture
3.5 Interrupt Servicing
The SPECTRA-4x155 driver services device interrupts using an Interrupt-Service Routine (ISR) that traps interrupts and a Deferred-Processing Routine (DPR) that actually processes the interrupt conditions and clears them. This lets the ISR execute quickly and exit. Most of the time-consuming processing of the interrupt conditions is deferred to the DPR by queuing the necessary interrupt-context information to the DPR task. The DPR function runs in the context of a separate task within the RTOS. Note: Since the DPR task processes potentially serious interrupt conditions, you should set the DPR task's priority higher than the application task interacting with the SPECTRA-4x155 driver. The driver provides system-independent functions, spe4x155ISR and spe4x155DPR. You must fill in the corresponding system-specific functions, sysSpe4x155ISRHandler and sysSpe4x155DPRTask. The system-specific functions isolate the system-specific communication mechanism (between the ISR and DPR) from the system-independent functions, spe4x155ISR and spe4x155DPR. Figure 6 illustrates the interrupt service model used in the SPECTRA-4x155 driver design. Figure 6: Interrupt Service Model
Interrupt Context Information
sysSpe4x155ISRHandler spe4x155ISR
sysSpe4x155DPRTask spe4x155DPR
Indication Callbacks Application
Note: Instead of using an interrupt service model, you can use a polling service model in the SPECTRA-4x155 driver to process the device's event-indication registers (see Figure 7).
Calling spe4x155ISR
An interrupt handler function, which is system dependent, must call spe4x155ISR. But first, the low-level interrupt-handler function must trap the device interrupts. You must implement this function to fit your own system. As a reference, an example implementation of the interrupt handler (sysSpe4x155ISRHandler) appears on page 114. You can customize this example implementation to suit your needs. The interrupt handler that you implement (sysSpe4x155ISRHandler) is installed in the interrupt vector table of the system processor. It is called when one or more SPECTRA-4x155 devices interrupt the processor. The interrupt handler then calls spe4x155ISR for each device in the active state that has interrupt processing enabled.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
27
Spectra-4x155 (PM5316) Driver Manual Software Architecture
The spe4x155ISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the SPECTRA-4x155. If at least one valid interrupt condition is found then spe4x155ISR fills an Interrupt-Service Vector (ISV) with this status information as well as the current device handle. The spe4x155ISR function also clears and disables all the device's interrupts detected. The sysSpe4x155ISRHandler function is then responsible to send this ISV buffer to the DPR task. Note: Normally you should save the status information for deferred-processing by implementing a message queue. The interrupt handler sends the status information to the queue inside
sysSpe4x155ISRHandler.
Calling spe4x155DPR
The sysSpe4x155DPRTask function is a system specific function that runs as a separate task within the RTOS. You should set the DPR task's priority higher than the application task(s) interacting with the SPECTRA-4x155 driver. In the message-queue implementation model, this task has an associated message queue. The task waits for messages from the ISR on this message queue. When a message arrives, sysSpe4x155DPRTask calls the DPR (spe4x155DPR) with the received ISV. Then spe4x155DPR processes the status information and takes appropriate action based on the specific interrupt condition detected. The nature of this processing can differ from system to system. Therefore, spe4x155DPR calls different indication callbacks for different interrupt conditions. Typically, you should implement these callback functions as simple message posting functions that post messages to an application task. However, you can implement the indication callback to perform processing within the DPR task context and return without sending any messages. In this case, ensure that this callback function does not call any API functions that would change the driver's state, such as spe4x155Delete. Also, ensure that the callback function is non-blocking because the DPR task executes while SPECTRA-4x155 interrupts are disabled. You can customize these callbacks to suit your system. See page 107 for example implementations of the callback functions. Note: Since the spe4x155ISR and spe4x155DPR routines themselves do not specify a communication mechanism, you have full flexibility in choosing a communication mechanism between the two. A convenient way to implement this communication mechanism is to use a message queue, which is a service that most RTOSs provide. You must implement the two system specific functions, sysSpe4x155ISRHandler and sysSpe4x155DPRTask. When the driver calls sysSpe4x155ISRHandlerInstall, the application installs sysSpe4x155ISRHandler in the interrupt vector table of the processor, and the sysSpe4x155DPRTask function is spawned as a task by the application. The sysSpe4x155ISRHandlerInstall function also creates the communication channel between sysSpe4x155ISRHandler and sysSpe4x155DPRTask. This communication channel is most commonly a message queue associated with the sysSpe4x155DPRTask.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
28
Spectra-4x155 (PM5316) Driver Manual Software Architecture
Similarly, during removal of interrupts, the driver removes sysSpe4x155ISRHandler from the microprocessor's interrupt vector table and deletes the task associated with
sysSpe4x155DPRTask.
As a reference, this manual provides example implementations of the interrupt installation and removal functions on page 114. You can customize these prototypes to suit your specific needs.
Calling spe4x155Poll
Instead of using an interrupt service model, you can use a polling service model in the SPECTRA-4x155 driver to process the device's event-indication registers. Figure 7 illustrates the polling service model used in the SPECTRA-4x155 driver design. Figure 7: Polling Service Model
spe4x155Poll Interrupt Context Information Indication Callbacks Application spe4x155DPR
spe4x155ISR
In polling mode, the application is responsible for calling spe4x155Poll often enough to service any pending error or alarm conditions. When spe4x155Poll is called, the spe4x155ISR function is called internally. The spe4x155ISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the SPECTRA-4x155. If at least one valid interrupt condition is found then spe4x155ISR fills an Interrupt-Service Vector (ISV) with this status information as well as the current device handle. The spe4x155ISR function also clears and disables all the device's interrupts detected. In polling mode, this ISV buffer is passed to the DPR task by calling spe4x155DPR internally.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
29
Spectra-4x155 (PM5316) Driver Manual Data Structures
4
DATA STRUCTURES
This section describes the elements of the driver that configure or control its behavior and therefore should be of interest to the application programmer. Included here are the constants, variables and structures that the SPECTRA-4x155 device driver uses to store initialization, configuration and statistics information. For more information on our naming convention, the reader is referred to Appendix A (page 129). Note: All (STM-1, AU-3) arrays that are used to pass 4 STM-1 and 3 AU-3 information are shown as arrays of size [4][3] in this document. However, in the driver source code, these arrays are declared to be of size [4+1][3+1] with the zeroeth element left unused. For example, an sts3c[4] array shown in this document is declared in the source code as sts3c[4+1]. The zeroeth element, sts3c[0], is left unused.
4.1
Constants
The following Constants are used throughout the driver code: *

: error codes used throughout the driver code, returned
by the API functions and used in the global error number field of the Module Data Block (MDB) and Device Data Block (DDB). See Appendix B (page 134) for a summary of the driver error codes. *
SPE4X155_MAX_DEVS: defines the maximum number of devices that can be supported by
this driver. This constant must not be changed without a thorough analysis of the consequences to the driver code. * *
SPE4X155_MOD_START, SPE4X155_MOD_IDLE, SPE4X155_MOD_READY: are the three
possible module states (stored in stateModule).
SPE4X155_START, SPE4X155_PRESENT, SPE4X155_ACTIVE, SPE4X155_INACTIVE: are the four possible device states (stored in stateDevice).
4.2
Structures Passed by the Application
These structures are defined for use by the application and are passed as argument to functions within the driver. These structures are the Module Initialization Vector (MIV), the Device Initialization Vector (DIV) and the Interrupt-Service Routine (ISR) mask.
Module Initialization Vector: MIV
Passed via the spe4x155ModuleOpen call, this structure contains all the information needed by the driver to initialize and connect to the RTOS.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
30
Spectra-4x155 (PM5316) Driver Manual Data Structures
*
maxDevs is used to inform the driver how many devices will be operating concurrently
during this session. The number is used to calculate the amount of memory that will be allocated to the driver. The maximum value that can be passed is SPE4X155_MAX_DEVS (see section 4.1). *
maxInitProfs is used to inform the driver how many Initialization profiles can be saved
during this session. The number is used to calculate the amount of memory that will be allocated by the driver. The maximum value that can be passed is SPE4X155_MAX_INIT_PROFS (see section 4.1). Table 1: SPECTRA-4x155 Module Initialization Vector: sSPE4X155_MIV Field Name
perrModule maxDevs maxInitProfs
Field Type
INT4 * UINT2 UINT2
Field Description (pointer to) errModule (see description in the MDB) Maximum number of devices supported during this session Maximum number of initialization profiles
Device Initialization Vector: DIV
Passed via the spe4x155Init call, this structure contains all the information needed by the driver to initialize a SPECTRA-4x155 device. This structure is also passed via the spe4x155SetInitProfile call when used as an initialization profile. * *
valid indicates that this initialization profile has been properly initialized and may be used by the user. This field should be ignored when the DIV is passed directly. pollISR is a flag that indicates the type of interrupt servicing the driver is to use. The
choices are `polling' (SPE4X155_POLL_MODE), and `interrupt driven' (SPE4X155_ISR_MODE). When configured in polling the interrupt capability of the device is NOT used, and the user is responsible for calling spe4x155Poll periodically. The actual processing of the event information is the same for both modes. *
cbackIO, cbackSOH, cbackLOH, cbackRPOH, cbackTPOH, cbackDPGM, and cbackAPGM are used to pass the address of application functions that will be used by the
Deferred-Processing Routine (DPR) to inform the application code of pending events. If these fields are set as NULL, then any events that might cause the DPR to `call back' the application will be processed during ISR processing but ignored by the DPR. Table 2: SPECTRA-4x155 Device Initialization Vector: sSPE4X155_DIV Field Name
valid
Field Type
UINT1
Field Description Indicates that this structure is valid
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
31
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
pollISR cbackIO
Field Type
eSPE4X155_POLL void *
Field Description Indicates the type of ISR / polling to do Address for the callback function for Input / Output (IO) Events Address for the callback function for Section Overhead (SOH) Events Address for the callback function for Line Overhead (LOH) Events Address for the callback function for Receive Path Overhead (RPOH) Events Address for the callback function for Transmit Path Overhead (TPOH) Events Address for the callback function for DROP Bus PRBS Generator/Monitor (DPGM) Events Address for the callback function for ADD Bus PRBS Generator/Monitor (APGM) Events When set to 1, the given STS-3 (STM-1) payload is concatenated (STS-3c). Enables the ring control ports Parameters for controlling the master clock configuration Signal fail accumulation period, saturation threshold, declaring threshold, and clearing threshold parameters. Signal degrade accumulation period, saturation threshold, declaring threshold, and clearing threshold parameters Counter configuration
cbackSOH
void *
cbackLOH
void *
cbackRPOH
void *
cbackTPOH
void *
cbackDPGM
void *
cbackAPGM
void *
sts3c[4]
UINT1
ringEna[4] cfgClock
UINT1 sSPE4X155_CFG_CLK
cfgSF[4]
sSPE4X155_CFG_SFSD
cfgSD[4]
sSPE4X155_CFG_SFSD
cfgCnt
sSPE4X155_CFG_CNT
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
32
Spectra-4x155 (PM5316) Driver Manual Data Structures
Clock Configuration (CFG_CLK) The user populates this structure to configure the device clocks. Table 3: Clock Config: sSPE4X155_CFG_CLK Field Name
pgmrchsel rclken tclken pgmrclken pgmrclksel pgmrtclken pgmrtclksel dropBusCfg addBusCfg
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description Selects the timing source of the PGMRCLK output Controls gating of the RCLK output Controls gating of the TCLK output Controls gating of the PGMRCLK output Selects the clock frequency of the PGMRCLK output Controls gating of the PGMTCLK output Selects the clock frequency of the PGMTCLK output DROP Bus clocking, 1=4x19.44 MHz or 0=77.76 MHz ADD Bus clocking, 1=4x19.44 MHz or 0=77.76 MHz
Signal Fail / Signal Degrade Configuration (CFG_SFSD) This structure contains all the fields needed to configure the signal fail (SF) and signal degrade (SD) accumulation period and thresholds. This structure contains all the fields needed to configure the device counters. It is part of the DIV and initialization profile. Table 4: Counters Config: sSPE4X155_CFG_SFSD Field Name
enable accumPeriod
Field Type
UINT1 UINT4
Field Description 1=Enable SF/SD The number of 8 KHz frames used to accumulate the B2 error subtotal Allowable number of B2 errors that can be accumulated during an evaluation window before an SF threshold event is declared
satuThresh
UINT2
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
33
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
declaThresh clearThresh
Field Type
UINT2 UINT2
Field Description The threshold for the declaration of the SF alarm The threshold of maximum B2 allowed errors for clearing the SF alarm 1=clearing window size == 8x declaring window size 0=clearing==declaring 1=limit number accumulated B2 errors to saturation threshold
clearMode
UINT1
satuMode
UINT1
Config Counters (CFG_CNT) The user passes this structure when invoking spe4x155CfgStats. It allows the user to configure the behavior of the device counts. Table 5: SPECTRA-4x155 Statistic Counters: sSPE4X155_CFG_CNT Field Name
sohBipBlk[4]
Field Type
UINT1
Field Description Controls the indication of Section BIP saturated errors. When non-zero, Section BIP errors are counted by block Controls the extraction of Line REI errors from the M1 byte. When non-zero, Line REI are counted by block Controls the indication of Line BIP errors. When nonzero, Line BIP errors are counted by block Controls the indication of receive path BIP errors. When non-zero, Path BIP errors are counted by block Controls the indication of transmit path BIP errors. When non-zero, Path BIP errors are counted by block Controls the indication of Path REI errors. When nonzero, Path REI errors are counted by block
lohReiBlk[4]
UINT1
lohBipBlk[4]
UINT1
rpohBipBlk[4][3]
UINT1
tpohBipBlk[4][3]
UINT1
rpohReiBlk[4][3]
UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
34
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
rpohMonrs[4][3]
Field Type
UINT1
Field Description When non-zero, selects the receive side pointer justification events counters to monitor the receive stream directly When zero, the counters accumulates pointer justification events on the DROP bus
ISR Enable/Disable Mask
Passed via the spe4x155SetMask, spe4x155GetMask and spe4x155ClearMask calls, this structure contains all the information needed by the driver to enable and disable any of the interrupts in the SPECTRA-4x155. The field value is non-zero if the interrupt is enabled, zero if disabled. Table 6: SPECTRA-4x155 ISR Mask: sSPE4X155_MASK Field Name
minte trool rrool[4] rdool[4] aparrerr[4] rdoolAux[4] sbipe[4] los[4] lof[4] oof[4] stiu[4] stim[4] oofAux[4]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description Master Interrupt Enable Transmit reference clock out of lock Receive reference clock out of lock Receive data out of lock ADD bus parity error Receive data out of lock state change Section BIP error Loss of Signal Loss of Frame Out of frame Section trace identifier unstable Section trace identifier mismatch Out of frame state change
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
35
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
losAux[4] lofAux[4] lbipe[4] lrei[4] sfber[4] sdber[4] cossm[4] coaps[4] apsbf[4] lais[4] lrdi[4] lrdiAux[4] laisAux[4] sfAux[4] sdAux[4] prdiAux[4][3] rpaisAux[4][3] psluAux[4][3] pslmAux[4][3] rplopAux[4][3] rplomAux[4][3] tiuAux[4][3] timAux[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description Loss of signal state change Loss of frame state change Line BIP error Line remote error indication error Signal failure Signal degrade Change of SSM message (Z1/S1) Change of APS bytes (K1, K2) APS byte failure Line alarm indication signal Line remote defect indication Line RDI state change Line AIS state change Signal fail Signal degrade Path RDI state change Path AIS state change Path signal label unstable state change Path signal label mismatch state change Loss of pointer state change Loss of multiframe state change Trace identifier unstable mode 1 state change Trace identifier mismatch state change
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
36
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
rplopcAux[4][3] rpaiscAux[4][3] tiu2Aux[4][3] perdiAux[4][3] rnewptr[4][3] rcopsl[4][3] rplopc[4][3] rplop[4][3] rpaisc[4][3] rpais[4][3] rprdi[4][3] rpbipe[4][3] rpreie[4][3] rperdi[4][3] rilljreq[4][3] rconcat[4][3] rdiscopa[4][3] rinvndf[4][3] rillptr[4][3] rpse[4][3] rnse[4][3] rndf[4][3] rlom[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description Loss of pointer concatenation state change Path AIS concatenation state change Trace identifier unstable mode 2 state change Path enhanced remote defect indication state change Reception of new pointer indication Path signal label change Path loss of pointer concatenated Path loss of pointer Path AIS concatenated Path AIS Path remote defect indication Path BIP error Path remote error indication Change of path enhanced remote defect indication Illegal pointer justification request Concatenation indicator error in STS-1/STM-0/AU-3. Change of pointer alignment event Invalid NDF code Illegal Pointer Positive pointer justification indication received Negative pointer justification indication received Detection of NDF_enable indication Loss of multiframe
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
37
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
rcoma[4][3] rese[4][3] rpjee[4][3]
Field Type
UINT1 UINT1 UINT1
Field Description Change of multiframe alignment Elastic store error DROP bus pointer justification event enable. Used with set/clear mask to enable/disable this interrupt DROP bus positive pointer justification inserted. Event reported when rpjee is enabled DROP bus negative pointer justification inserted. Event reported when rpjee is enabled Path connection unequipped Path trace identifier unstable Path trace identifier mismatch Path signal label mismatch Path signal label unstable DROP generator signal DROP monitor error detected in received PRBS byte DROP monitor synchronization state change DROP monitor signal verification state by a slave monitor Change in transmit loss of pointer concatenation state Change in transmit path AIS concatenation state Change in transmit path AIS state Change in transmit loss of pointer state Change in transmit loss of multiframe state Elastic store FIFO overflow/underflow error
rppji[4][3]
UINT1
rnpji[4][3]
UINT1
rpuneq[4][3] rptiu[4][3] rptim[4][3] rpslm[4][3] rpslu[4][3] dpgmGenSig[4][3] dpgmMonErr[4][3] dpgmMonSync[4][3] dpgmMonSig[4][3]
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
tplopcAux[4][3] tpaiscAux[4][3] tpaisAux[4][3] tplopAux[4][3] tplomAux[4][3] tese[4][3]
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
38
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
tpjee[4][3]
Field Type
UINT1
Field Description Enable interrupts for pointer justification events inserted in the transmit stream. Used with set/clear mask to enable/disable this interrupt Positive pointer justification event inserted into transmit stream reported when tpjee is enabled Negative pointer justification event inserted into transmit stream. Event reported when tpjee is enabled New point indication received Change in transmit AU-3 loss of pointer concatenation status Change in transmit loss of pointer status Change in transmit path AIS concatenation status Change in transmit path AIS status Change in transmit path remote defect indication Change in transmit path BIP error status Change in transmit path extended remote error indication status Illegal justification request event Discontinuous pointer change Invalid NDF observed in receive stream Concatenation error Illegal Pointer Negative pointer justification event detected in transmit stream Positive pointer justification event detected in transmit stream NDF enable pattern observed in receive stream
tppji[4][3]
UINT1
tnpji[4][3]
UINT1
tnewptr[4][3] tplopc[4][3]
UINT1 UINT1
tplop[4][3] tpaisc[4][3] tpais[4][3] tprdi[4][3] tpbipe[4][3] tprei[4][3]
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
tillreq[4][3] tdiscopa[4][3] tinvndf[4][3] tconcat[4][3] tillptr[4][3] tnse[4][3]
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
tpse[4][3]
UINT1
tndf[4][3]
UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
39
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
tlom[4][3] tcoma[4][3] apgmGenSig[4][3] apgmMonErr[4][3] apgmMonSync[4][3] apgmMonSig[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description Change in loss of multiframe status in received stream Change in multiframe alignment ADD generator signal ADD monitor error detected in received PRBS byte ADD monitor synchronization state change ADD monitor signal verification state by a slave monitor
Statistic Counters (CNT)
This structure, as well as its component structures, are being used by the statistics collection APIs to retrieve the device counts. The user can either collect all statistics at once by using spe4x155GetCnt, collect statistics from individual blocks using spe4x155GetCntSOH, spe4x155GetCntLOH, and/or spe4x155GetCntPOH. Counters Top-level Structure Table 7: SPECTRA-4x155 Statistic Counters: sSPE4X155_STAT_CNT Field Name
cntSOH[4]
Field Type
sSPE4X155_STAT_CNT_SOH
Field Description Statistics counters of the Section Overhead (SOH) Statistics counters of the Line Overhead (LOH) Statistics counters of the Receive Path Overhead (RPOH) Statistics counters of the Transmit Path Overhead (TPOH) Statistics counters for pointer justifications (PJ)
cntLOH[4]
sSPE4X155_STAT_CNT_LOH
cntRPOH[4][3]
sSPE4X155_STAT_CNT_RPOH
cntTPOH[4][3]
sSPE4X155_STAT_CNT_TPOH
cntPJ[4][3]
sSPE4X155_STAT_CNT_PJ
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
40
Spectra-4x155 (PM5316) Driver Manual Data Structures
Section Overhead (SOH) Statistics Counters Table 8: SPECTRA-4x155 Section Overhead Statistics Counters: sSPE4X155_STAT_CNT_SOH Field Name
sohBip
Field Type
UINT4
Field Description Section BIP errors counter
Line Overhead (LOH) Statistics Counters Table 9: SPECTRA-4x155 Line Overhead Status: sSPE4X155_STAT_CNT_LOH Field Name
lohBip lohRei
Field Type
UINT4 UINT4
Field Description Line BIP errors counter Line REI error counter
Receive Path Overhead (RPOH) Statistics Counters Table 10: SPECTRA-4x155 Path Processing Statistics Counters: sSPE4X155_STAT_CNT_RPOH Field Name
rpohBip rpohRei pohDPGMPrse
Field Type
UINT4 UINT4 UINT4
Field Description Path BIP error counter Path REI error counter Number of PRBS byte errors detected since the last accumulation interval. Errors are only accumulated in the synchronized state and each PRBS data byte can have a maximum of 1 errors
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
41
Spectra-4x155 (PM5316) Driver Manual Data Structures
Transmit Path Overhead (TPOH) Statistics Counters Table 11: SPECTRA-4x155 Transmit Path Processing Statistics Counters: sSPE4X155_STAT_CNT_TPOH Field Name
tpohBip pohAPGMPrse
Field Type
UINT4 UINT4
Field Description Path BIP error counter Number of PRBS byte errors detected since the last accumulation interval. Errors are only accumulated in the synchronized state and each PRBS data byte can have a maximum of 1 errors
Pointer Justification (PJ) Statistics Counters Table 12: SPECTRA-4x155 Pointer Justification Statistics Counters: sSPE4X155_STAT_CNT_PJ Field Name
rPosJust rNegJust tPosJust tNegJust
Field Type
UINT4 UINT4 UINT4 UINT4
Field Description Positive pointer justification event counter - receive side Negative pointer justification event counter - receive side Positive pointer justification event counter - transmit side Negative pointer justification event counter - transmit side
Time-Slot structure: TSLOT
Passed inside the Time-Slot Interchange (TSI) API function calls, this structure fully describes a single STM-1, AU-3 timeslot as configured in the TSI. Table 13: SPECTRA-4x155 Time-Slot: sSPE4X155_TSLOT Field Name
stm1 au3
Field Type
UINT1 UINT1
Field Description STM-1 index AU3 index
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
42
Spectra-4x155 (PM5316) Driver Manual Data Structures
PRBS Configuration Structure
Passed inside the PRBS (DPGM and APGM) API function calls, this structure fully describes PRBS generator and monitor configuration. Table 14: SPECTRA-4x155 PRBS Configuration: sSPE4X155_CFG_PRBS Field Name
enable
Field Type
UINT1
Field Description Enable PRBS generator/monitor 0=disable 1=enable Fixed stuff enable 0=insert in fixed stuff bytes 1=do not Invert PRBS value 0=do not invert 1=invert Generator, autonomous input mode Monitor, allows automatic resynchronization 0=disable, 1=enable
fsEnable
UINT1
invPrbs
UINT1
autoMode
UINT1
Device and Alarm Status
Table 15: SPECTRA-4x155 Alarm Status: sSPE4X155_STATUS Field Name
statIO statSOH[4]
Field Type
sSPE4X155_STATUS_IO sSPE4X155_STATUS_SOH
Field Description Alarm status of the Input / Output (IO) Alarm status of the Section Overhead (SOH) Alarm status of the Line Overhead (LOH) Alarm status of the Receive Path Overhead (RPOH) Alarm status for the Transmit Path Overhead (TPOH)
statLOH[4]
sSPE4X155_STATUS_LOH
statRPOH[4][3]
sSPE4X155_STATUS_RPOH
statTPOH[4][3]
sSPE4X155_STATUS_TPOH
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
43
Spectra-4x155 (PM5316) Driver Manual Data Structures
Input / Output (IO) Alarm Status Table 16: SPECTRA-4x155 Input / Output Alarm Status: sSPE4X155_STATUS_IO Field Name
refclkActive
Field Type
UINT1
Field Description Monitors for low to high transitions on the REFCLK reference clock input Transmit reference clock out of lock Monitors for low to high transitions on the DCK input Monitors for low to high transitions on the ACK input Value of SENDLRDI bit position in the transmit ring control port Value of SENDLAIS bit position in the transmit ring control port Receive reference clock out of lock Receive data clock out of lock Monitors for low to high transitions in the corresponding APL[m], AC1J1V1[m] and ADP[m] inputs. addControlAct[n] is non-zero when rising edges have been observed on all these signals Monitors for low to high transitions in the corresponding AD[7:0], AD[15:8}, AD[23:16], or AD[31:24] bus when configured for byte Telecom ADD bus mode. addDataAct[n] is non-zero when rising edges have been observed on all the required signals in the corresponding Telecom ADD bus
trool dckAct ackAct insLRDI[4]
UINT1 UINT1 UINT1 UINT1
insLAIS[4]
UINT1
rrool[4] rdool[4] addControlAct[4]
UINT1 UINT1 UINT1
addDataAct[4]
UINT1
Section Overhead (SOH) Alarm Status Table 17: SPECTRA-4x155 Section Overhead Alarm Status: sSPE4X155_STATUS_SOH Field Name
los
Field Type
UINT1
Field Description LOS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
44
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
lof oof tiu tim
Field Type
UINT1 UINT1 UINT1 UINT1
Field Description LOF OOF Section trace identifier unstable Section trace identifier mismatch
Line Overhead (LOH) Alarm Status Table 18: SPECTRA-4x155 Line Overhead Status: sSPE4X155_STATUS_LOH Field Name
sfber sdber psbf lrdi lais
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1
Field Description SF SD APS byte failure Line RDI Line AIS
Receive Path Overhead (RPOH) Alarm Status Table 19: SPECTRA-4x155 Receive Path Processing Alarm Status: sSPE4X155_STATUS_RPOH Field Name
ptiu ptim au3paisc au3plopc pais
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1
Field Description Path trace identifier unstable Path trace identifier mismatch STS-1 Path AIS concatenated STS-1 Path LOP concatenated Path AIS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
45
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
lop prdi perdi lom uneq pslm pslu dropGenSig dropMonSig dropMonSync
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description Path LOP Path RDI Path Enhanced RDI Loss of multiframe declared Path unequipped Path signal label mismatch Path signal label unstable Generator signature status Monitor signature status DROP monitor change of synchronization state
Transmit Path Overhead (TPOH) Alarm Status Table 20: SPECTRA-4x155 Transmit Path Processing Alarm Status: sSPE4X155_STATUS_TPOH Field Name
au3lopc
Field Type
UINT1
Field Description AU-3 concatenation path loss of pointer in transmit STS-1 stream AU-3 concatenation path AIS in transmit STS-1 stream Loss of pointer detected Path alarm indication signal detected Loss of multiframe declared Generator signature status Monitor signature status ADD monitor change of synchronization state
au3paisc lop pais lom addGenSig addMonSig addMonSync
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
46
Spectra-4x155 (PM5316) Driver Manual Data Structures
4.3
Structures in the Driver's Allocated Memory
These structures are defined and used by the driver and are part of the context memory allocated when the driver is opened. These structures are the Module Data Block (MDB) and the Device Data Block (DDB).
Module Data Block: MDB
The MDB is the top-level structure for the module. It contains configuration data about the module level code and pointers to configuration data about the device level codes. *
errModule indicates that most of the module API functions return a specific error code directly. When the returned code is SPE4X155_FAILURE, this indicates that the top-level
function was not able to carry the specified error code back to the application. Under those circumstances, the proper error code is recorded in this element. The element is the first in the structure so that the user can cast the MDB pointer into a INT4 pointer and retrieve the local error (this eliminates the need to include the MDB template into the application code). * *
valid indicates that this structure has been properly initialized and may be read by the user. stateModule contains the current state of the module and could be set to: SPE4X155_MOD_START, SPE4X155_MOD_IDLE or SPE4X155_MOD_READY.
Table 21: SPECTRA-4x155 Module Data Block: sSPE4X155_MDB Field Name
errModule valid stateModule
Field Type
INT4 UINT1 eSPE4X155_MOD_STATE
Field Description Global error Indicator for module calls Indicates that this structure has been initialized Module state - can be one of the following IDLE or READY Maximum number of devices supported Number of devices currently registered Maximum number of initialization profiles (array of) Device Data Blocks (DDB) in context memory (array of) Initialization profiles in context memory
maxDevs numDevs maxInitProfs pddb
UINT2 UINT2 UINT2 sSPE4X155_DDB *
pinitProfs
sSPE4X155_DIV *
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
47
Spectra-4x155 (PM5316) Driver Manual Data Structures
Device Data Block: DDB
The DDB is the top-level structure for each device. It contains configuration data about the device level code and pointers to configuration data about device level sub-blocks. *
errDevice indicates that most of the device API functions return a specific error code directly. When the returned code is SPE4X155_FAILURE, this indicates that the top-level
function was not able to carry the specific error code back to the application. In addition, some device functions do not return an error code. Under those circumstances, the proper error code is recorded in this element. The element is the first in the structure so that the user can cast the DDB pointer to a INT4 pointer and retrieve the local error (this eliminates the need to include the DDB template in the application code). * * *
valid indicates that this structure has been properly initialized and may be read by the user. stateDevice contains the current state of the device and could be set to: SPE4X155_START, SPE4X155_PRESENT, SPE4X155_ACTIVE or SPE4X155_INACTIVE. usrCtxt is a value that can be used by the user to identify the device during the execution of the callback functions. It is passed to the driver when spe4x155Add is called and returned to
the user in the DPV when a callback function is invoked. The element is unused by the driver itself and may contain any value. Table 22: SPECTRA-4x155 Device Data Block: sSPE4X155_DDB Field Name
errDevice valid
Field Type
INT4 UINT1
Field Description Global error indicator for device calls Indicates that this structure has been initialized Device State - can be one of the following PRESENT, ACTIVE or INACTIVE Base address of the device Stores the user's context for the device. It is passed as an input parameter when the driver invokes an application callback Profile number used at initialization Indicates the current type of ISR / polling Address for the callback function for Input / Output (IO) Events
stateDevice
eSPE4X155_DEV_STATE
baseAddr usrCtxt
UINT1 * void *
profileNum pollISR cbackIO
UINT2 eSPE4X155_POLL void *
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
48
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
cbackSOH
Field Type
void *
Field Description Address for the callback function for Section Overhead (SOH) Events Address for the callback function for Line Overhead (LOH) Events Address for the callback function for Receive Path Overhead (RPOH) Events Address for the callback function for Transmit Path Overhead (TPOH) Events Address for the callback function for DROP Bus PRBS Generator/Monitor (DPGM) Events Address for the callback function for ADD Bus PRBS Generator/Monitor (APGM) Events When set to 1, the given STS-3 (STM-1) payload is concatenated (STS-3c). Enables the ring control ports Parameters for controlling the master clock configuration DROP Bus PRBS Generator configuration block DROP Bus PRBS Monitor configuration block ADD Bus PRBS Generator configuration block ADD Bus PRBS Monitor configuration block Signal fail accumulation period, saturation threshold, declaring threshold, and clearing threshold parameters
cbackLOH
void *
cbackRPOH
void *
cbackTPOH
void *
cbackDPGM
void *
cbackAPGM
void *
sts3c[4]
UINT1
ringEna[4] cfgClock
UINT1 sSPE4X155_CFG_CLK
cfgDropGen[4][3]
sSPE4X155_CFG_PRBS
cfgDropMon[4][3]
sSPE4X155_CFG_PRBS
cfgAddGen[4][3]
sSPE4X155_CFG_PRBS
cfgAddMon[4][3]
sSPE4X155_CFG_PRBS
cfgSF[4]
sSPE4X155_CFG_SFSD
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
49
Spectra-4x155 (PM5316) Driver Manual Data Structures
Field Name
cfgSD[4]
Field Type
sSPE4X155_CFG_SFSD
Field Description Signal degrade accumulation period, saturation threshold, declaring threshold, and clearing threshold parameters Counter configuration Device version number application callback event thresholds number of events that have occurred since the last time the thresholds have been reached Interrupt Enable Mask
cfgCnt ver threshold threshCntr
sSPE4X155_CFG_CNT UINT1 sSPE4X155_MASK sSPE4X155_MASK
mask
sSPE4X155_MASK
4.4
Structures Passed through RTOS Buffers
Interrupt-Service Vector: ISV
This buffer structure is used to capture the status of the device (during a poll or ISR processing) for use by the Deferred-Processing Routine (DPR). It is the template for all device registers that are involved in exception processing. It is the application's responsibility to create a pool of ISV buffers (using this template to determine the buffer's size) when the driver calls the user-supplied sysSpe4x155BufferStart function. An individual ISV buffer is then obtained by the driver via sysSpe4x155ISVBufferGet and returned to the `pool' via sysSpe4x155ISVBufferRtn. Table 23: SPECTRA-4x155 Interrupt-Service Vector: sSPE4X155_ISV Field Name
deviceHandle mask
Field Type
sSPE4X155_HNDL sSPE4X155_MASK
Field Description Handle to the device in cause ISR mask filled with interrupt status
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
50
Spectra-4x155 (PM5316) Driver Manual Data Structures
Deferred-Processing Vector: DPV
This block is used in two ways. First it is used to determine the size of buffer required by the RTOS for use in the driver. Second it is the template for data that is assembled by the DPR and sent to the application code. Note: the application code is responsible for returning this buffer to the RTOS buffer pool. The DPR divides the SPECTRA-4x155 into 7 sections: IO, SOH, LOH, RPOH, TPOH, DPGM, and APGM. Seven user-supplied callback routines (one per section) are used to inform the application which section of the device has caused the event being reported. Table 24: SPECTRA-4x155 Deferred-Processing Vector: sSPE4X155_DPV Field Name
event cause
Field Type
SPE4X155_DPR_EVENT UINT4
Field Description Event being reported Reason for the Event
4.5
Global Variable
Although most of the variables within the driver are not meant to be used by the application code, there is one global variable that can be of great use to the application code.
spe4x155Mdb: A global pointer to the Module Data Block (MDB). The content of this global variable should be considered read-only by the application.
*
errModule: This structure element is used to store an error code that specifies the reason for
an API function's failure. The field is only valid for functions that do not return an error code or when a value of SPE4X155_FAILURE is returned. * *
stateModule: This structure element is used to store the module state (as shown in Figure
3).
pddb[ ]: An array of pointers to the individual Device Data Blocks. The user is cautioned that a DDB is only valid if the valid flag is set. Note that the array of DDBs is in no
particular order.
errDevice: This structure element is used to store an error code that specifies the reason
for an API function's failure. The field is only valid for functions that do not return an error code or when a value of SPE4X155_FAILURE is returned.
stateDevice: This structure element is used to store the device state (as shown in
Figure 3).
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
51
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
5
APPLICATION PROGRAMMING INTERFACE
This section provides a detailed description of each function that is a member of the SPECTRA4x155 driver Application Programming Interface (API). The API functions typically execute in the context of an application task. Note: These functions are not re-entrant. This means that two application tasks can not invoke the same API at the same time. However the driver protects its data structures from concurrent accesses by the application and the Deferred-Processing Routine (DPR) task.
5.1
Module Management
The module management is a set of API functions that are used by the application to open, start, stop and close the driver module. These functions take care of initializing the driver, allocating memory and all RTOS resources needed by the driver. They are also used to change the module state. For more information on the module states see the state diagram on page 23. For a typical module management flow diagram see page 25.
Opening the Driver Module: spe4x155ModuleOpen
This function performs module level initialization of the device driver. This involves allocating all of the memory needed by the driver and initializing the internal structures. Prototype Inputs
INT4 spe4x155ModuleOpen(sSPE4X155_MIV *pmiv) pmiv
: (pointer to) Module Initialization Vector (MIV)
Outputs Returns
Places the address of the MDB into the MIV passed by the application Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_MODULE_STATE
SPE4X155_ERR_INVALID_MIV SPE4X155_ERR_MEM_ALLOC
Valid States Side Effects
SPE4X155_MOD_START
Changes the MODULE state to SPE4X155_MOD_IDLE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
52
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Closing the Driver Module: spe4x155ModuleClose
This function performs module level shutdown of the driver. This involves deleting all devices being controlled by the driver (by calling spe4x155Delete for each device) and de-allocating all the memory allocated by the driver. Prototype Inputs Outputs Returns
INT4 spe4x155ModuleClose(void)
None None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_MODULE_STATE
SPE4X155_MOD_IDLE, SPE4X155_MOD_READY
Valid States Side Effects
Changes the MODULE state to SPE4X155_MOD_START
Starting the Driver Module: spe4x155ModuleStart
This function connects the RTOS resources to the driver. This involves initializing buffers and installing the Interrupt-Service Routine (ISR) handler and DPR task. Upon successful return from this function the driver is ready to add devices. Prototype Inputs Outputs Returns
INT4 spe4x155ModuleStart(void)
None None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_MODULE_STATE
SPE4X155_MOD_IDLE
Valid States Side Effects
Changes the MODULE state to SPE4X155_MOD_READY
Stopping the Driver Module: spe4x155ModuleStop
This function disconnects the RTOS resources from the driver. This involves freeing-up buffers and uninstalling the ISR handler and the DPR task. If there are any registered devices, spe4x155Delete is called for each. Prototype Inputs
INT4 spe4x155ModuleStop(void)
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
53
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_MODULE_STATE
SPE4X155_MOD_READY
Valid States Side Effects
Changes the MODULE state to SPE4X155_MOD_IDLE
5.2
Profile Management
This section describes the functions that add, get and clear an initialization profile. Initialization profiles allow the user to store pre-defined Device Initialization Vectors (DIV) that are validated ahead of time. When the device initialization function is invoked only a profile number need to be passed. This method simplifies and expedites the initialization process.
Setting an Initialization Profile: spe4x155SetInitProfile
This function creates an initialization profile that is stored by the driver. A device can now be initialized by simply passing the initialization profile number. Prototype Inputs
INT4 spe4x155SetInitProfile(sSPE4X155_DIV *pProfile, UINT2 *pProfileNum) pProfile pProfileNum
: (pointer to) initialization profile being added : (pointer to) profile number to be assigned by the driver : profile number assigned by the driver
Outputs Returns
pProfileNum
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_MODULE_STATE
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_PROFILE SPE4X155_ERR_PROFILES_FULL
Valid States Side Effects
SPE4X155_MOD_IDLE, SPE4X155_MOD_READY
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
54
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Getting an Initialization Profile: spe4x155GetInitProfile
This function gets the content of an initialization profile given its profile number. Prototype Inputs
INT4 spe4x155GetInitProfile(UINT2 profileNum, sSPE4X155_DIV *pProfile) profileNum pProfile pProfile
: initialization profile number : (pointer to) initialization profile : contents of the corresponding profile
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_MODULE_STATE
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_PROFILE_NUM
Valid States Side Effects
SPE4X155_MOD_IDLE, SPE4X155_MOD_READY
None
Deleting an Initialization Profile: spe4x155ClrInitProfile
This function deletes an initialization profile given its profile number. Prototype Inputs Outputs Returns
INT4 spe4x155ClrInitProfile(UINT2 profileNum) profileNum
: initialization profile number
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_MODULE_STATE
SPE4X155_ERR_INVALID_PROFILE_NUM SPE4X155_MOD_IDLE, SPE4X155_MOD_READY
Valid States Side Effects
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
55
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
5.3
Device Management
The device management is a set of API functions that are used by the application to control the device. These functions take care of initializing a device in a specific configuration, enabling the device general activity as well as enabling interrupt processing for that device. They are also used to change the software state for that device. For more information on the device states see the state diagram on page 23. For a typical device management flow diagram see page 26.
Adding a Device: spe4x155Add
This function verifies the presence of a new device in the hardware then returns a handle back to the user. The device handle is passed as a parameter of most of the device API Functions. It's used by the driver to identify the device on which the operation is to be performed. Prototype Inputs
sSPE4X155_HNDL spe4x155Add(void *usrCtxt, UINT1 *baseAddr, INT4 **pperrDevice) usrCtxt baseAddr pperrDevice
: user context for this device : base address of the device : (pointer to) an area of memory
Outputs
ERROR code written to the MDB on failure
SPE4X155_ERR_INVALID_MODULE_STATE SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_DEVS_FULL SPE4X155_ERR_DEV_ALREADY_ADDED SPE4X155_ERR_INVALID_DEV pperrDevice : (pointer to) errDevice (inside the
DDB) Returns Success = device handle (to be used bas an argument to most of the SPECTRA-4x155 APIs) Failure = NULL (pointer)
SPE4X155_MOD_READY
Valid States Side Effects
Changes the DEVICE state to SPE4X155_PRESENT
Deleting a Device: spe4x155Delete
This function is used to remove the specified device from the list of devices being controlled by the SPECTRA-4x155 driver. Deleting a device involves invalidating the DDB for that device and releasing its associated device handle. Prototype
INT4 spe4x155Delete(sSPE4X155_HNDL deviceHandle)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
56
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Inputs Outputs Returns
deviceHandle
: device handle (from spe4x155Add)
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_PRESENT, SPE4X155_ACTIVE, SPE4X155_INACTIVE
Valid States Side Effects
Changes the DEVICE state to SPE4X155_START
Initializing a Device: spe4x155Init
This function initializes the Device Data Block (DDB) associated with that device during spe4x155Add, applies a soft reset to the device and configures it according to the DIV passed by the application. If the DIV is passed as a NULL the profile number is used. A profile number of zero indicates that all the register bits are to be left in their default state (after a soft reset). Note that the profile number is ignored UNLESS the passed DIV is NULL. Prototype Inputs
INT4 spe4x155Init(sSPE4X155_HNDL deviceHandle, sSPE4X155_DIV *pdiv, UINT2 profileNum) deviceHandle pdiv profileNum
: device handle (from spe4x155Add) : (pointer to) Device Initialization Vector : profile number (ignored if pdiv is NULL)
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_DIV SPE4X155_ERR_INVALID_PROFILE_NUM
Valid States Side Effects
SPE4X155_PRESENT
Changes the DEVICE state to SPE4X155_INACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
57
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Updating the Configuration of a Device: spe4x155Update
This function updates the configuration of the device as well as the Device Data Block (DDB) associated with that device according to the DIV passed by the application. The only difference between spe4x155Update and spe4x155Init is that no soft reset will be applied to the device. Prototype
INT4 spe4x155Update(sSPE4X155_HNDL deviceHandle, sSPE4X155_DIV *pdiv, UINT2 profileNum) deviceHandle pdiv profileNum
Inputs
: device handle (from spe4x155Add) : (pointer to) Device Initialization Vector (DIV) : profile number (ignored if pdiv is NULL)
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_DIV SPE4X155_ERR_INVALID_PROFILE_NUM
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Resetting a Device: spe4x155Reset
This function applies a software reset to the SPECTRA-4x155 device. It also resets all the DDB contents (except for the user context). This function is typically called before re-initializing the device (via spe4x155Init). Prototype Inputs Outputs Returns
INT4 spe4x155Reset(sSPE4X155_HNDL deviceHandle) deviceHandle
: device handle (from spe4x155Add)
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_PRESENT, SPE4X155_ACTIVE, SPE4X155_INACTIVE
Valid States Side Effects
Changes the DEVICE state to SPE4X155_PRESENT
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
58
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Activating a Device: spe4x155Activate
This function restores the state of a device after a de-activate. Interrupts may be re-enabled. Prototype Inputs Outputs Returns
INT4 spe4x155Activate(sSPE4X155_HNDL deviceHandle deviceHandle
: device handle (from spe4x155Add)
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_INACTIVE
Valid States Side Effects
Changes the DEVICE state to SPE4X155_ACTIVE
De-Activating a Device: spe4x155DeActivate
This function de-activates the device from operation. Interrupts are masked and the device is put into a quiet state via enable bits. Prototype Inputs Outputs Returns
INT4 spe4x155DeActivate(sSPE4X155_HNDL deviceHandle deviceHandle
: device handle (from spe4x155Add)
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ACTIVE
Valid States Side Effects
Changes the DEVICE state to SPE4X155_INACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
59
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
5.4
Device Read and Write
Reading from Device Registers: spe4x155Read
This function can be used to read a register of a specific SPECTRA-4x155 device by providing the register number. This function derives the actual address location based on the device handle and register number inputs. It then reads the contents of this address location using the system specific macro, sysSpe4x155Read. Note that a failure to read returns a zero and any error indication is written to the associated DDB. Prototype Inputs
UINT1 spe4x155Read(sSPE4X155_HNDL deviceHandle, UINT2 regNum) deviceHandle regNum
: device handle (from spe4x155Add) : register number
Outputs
ERROR code written to the MDB
SPE4X155_ERR_INVALID_DEV
ERROR code written to the DDB
SPE4X155_ERR_INVALID_REG
Returns Valid States Side Effects
Success = value read Failure = 0
SPE4X155_PRESENT, SPE4X155_ACTIVE, SPE4X155_INACTIVE
May affect registers that change after a read operation
Writing to Device Registers: spe4x155Write
This function can be used to write to a register of a specific SPECTRA-4x155 device by providing the register number. This function derives the actual address location based on the device handle and register number inputs. It then writes the contents of this address location using the system specific macro, sysSpe4x155Write. Note that a failure to write returns a zero and any error indication is written to the DDB. Prototype Inputs
UINT1 spe4x155Write(sSPE4X155_HNDL deviceHandle, UINT2 regNum, UINT1 value) deviceHandle regNum value
: device handle (from spe4x155Add) : register number : value to be written
Outputs
ERROR code written to the MDB
SPE4X155_ERR_INVALID_DEV
ERROR code written to the DDB
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
60
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
SPE4X155_ERR_INVALID_REG
Returns Valid States Side Effects
Success = value written Failure = 0
SPE4X155_PRESENT, SPE4X155_ACTIVE, SPE4X155_INACTIVE
May change the configuration of the device
Reading from a block of Device Registers: spe4x155ReadBlock
This function can be used to read a register block of a specific SPECTRA-4x155 device by providing the starting register number, and the size to read. This function derives the actual start address location based on the device handle and starting register number inputs. It then reads the contents of this data block using multiple calls to the system specific macro, sysSpe4x155Read. Note that a failure to read returns a zero and any error indication is written to the DDB. It is the user's responsibility to allocate enough memory for the block read. Prototype
void spe4x155ReadBlock(sSPE4X155_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT1 *pblock) deviceHandle startRegNum size pblock
Inputs
: device handle (from spe4x155Add) : starting register number : size of the block to read : (pointer to) the block to read
Outputs
ERROR code written to the MDB
SPE4X155_ERR_INVALID_DEV
ERROR code written to the DDB
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_REG pblock
: (pointer to) the block read
Returns Valid States Side Effects
Success = Last register value read Failure = 0
SPE4X155_PRESENT, SPE4X155_ACTIVE, SPE4X155_INACTIVE
May affect registers that change after a read operation
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
61
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Writing to a Block of Device Registers: spe4x155WriteBlock
This function can be used to write to a register block of a specific SPECTRA-4x155 device by providing the starting register number and the block size. This function derives the actual starting address location based on the device handle and starting register number inputs. It then writes the contents of this data block using multiple calls to the system specific macro, sysSpe4x155Write. A bit from the passed block is only modified in the device's registers if the corresponding bit is set in the passed mask. Note that any error indication is written to the DDB Prototype
void spe4x155WriteBlock(sSPE4X155_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT1 *pblock, UINT1 *pmask) deviceHandle startRegNum size pblock pmask
Inputs
: device handle (from spe4x155Add) : starting register number : size of block to read : (pointer to) block to write : (pointer to) mask
Outputs
ERROR code written to the MDB
SPE4X155_ERR_INVALID_DEV
ERROR code written to the DDB
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_REG
Returns Valid States Side Effects
Success = Last register value written Failure = 0
SPE4X155_PRESENT, SPE4X155_ACTIVE, SPE4X155_INACTIVE
May change the configuration of the device
5.5
Input Output
The I/O section provides functions to control the ring control ports on the device, giving the application an interface for applying line AIS and RDI, as well as configuration of the Time Slot Interchange (TSI).
Sending Line AIS Maintenance Signal: spe4x155RINGLineAISControl
This function forces a mate SPECTRA-4x155 to send the line AIS maintenance signal. Prototype
INT4 spe4x155RINGLineAISControl(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
62
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Inputs
deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start/stop Line-AIS insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_ARG
SPE4X155_ERR_INVALID_DEV SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Sending Line RDI Maintenance Signal: spe4x155RINGLineRDIControl
This function forces a mate SPECTRA-4x155 to send the line RDI maintenance signal. Prototype Inputs
INT4 spe4x155RINGLineRDIControl(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start/stop Line-AIS insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_ARG
SPE4X155_ERR_INVALID_DEV SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Creating a Timeslot Mapping: spe4x155IOMapSlot
This function maps a source timeslot to one or more destination timeslots. This function supports a unicast or a multicast mapping. Prototype
INT4 spe4x155IOMapSlot(sSPE4X155_HNDL deviceHandle, UINT1 direction, sSPE4X155_TSLOT *psrcSlot, sSPE4X155_TSLOT *pdestSlot, UINT1 numDestSlots) deviceHandle
Inputs
: device handle (from spe4x155Add)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
63
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
direction
psrcSlot pdestSlot numDestSlots
: direction (symmetry) 0 = Drop 1 = Add : (pointer to) source timeslot : (pointer to) destination timeslot(s) : number of destination timeslots
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_ARG
SPE4X155_ERR_INVALID_DEV SPE4X155_ACTIVE, SPE4X155_INACTIVE
Valid States Side Effects
None
Determining if a Timeslot is being Multicasted: spe4x155IOIsMulticast
This function informs the user of whether or not a source timeslot is being multicasted. Prototype
INT4 spe4x155IOIsMulticast(sSPE4X155_HNDL deviceHandle, UINT1 direction, sSPE4X155_TSLOT *psrcSlot, UINT1 *pnumDestSlots) deviceHandle direction
Inputs
psrcSlot pnumDestSlots
: device handle (from spe4x155Add) : direction (symmetry) 0 = Drop 1 = Add : (pointer to) source timeslot : (pointer to) allocated memory : number of destination timeslot(s)
Outputs Returns
pnumDestSlots
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_ARG
SPE4X155_ERR_INVALID_DEV SPE4X155_ACTIVE, SPE4X155_INACTIVE
Valid States Side Effects
None
Getting Destination Timeslot(s): spe4x155IOGetDestSlot
This function retrieves a list of destination timeslots mapped to a specified source timeslot. Prototype
INT4 spe4x155IOGetDestSlot(sSPE4X155_HNDL deviceHandle, UINT1 direction, sSPE4X155_TSLOT
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
64
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
*psrcSlot, sSPE4X155_TSLOT *pdestSlot, UINT1 *pnumDestSlots)
Inputs
deviceHandle direction
psrcSlot pdestSlot pnumDestSlots
: device handle (from spe4x155Add) : direction (symmetry) 0 = Drop 1 = Add : (pointer to) source timeslot : (pointer to) allocated memory : (pointer to) allocated memory : destination timeslot : number of destination timeslot(s)
Outputs
pdestSlot pnumDestSlots
Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_ARG
SPE4X155_ERR_INVALID_DEV SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Getting Source Timeslot: spe4x155IOGetSrcSlot
This function retrieves the source timeslot mapped to a specified destination timeslot. Prototype
INT4 spe4x155IOGetSrcSlot(sSPE4X155_HNDL deviceHandle, UINT1 direction, sSPE4X155_TSLOT *pdestSlot, sSPE4X155_TSLOT *psrcSlot) deviceHandle direction
Inputs
pdestSlot psrcSlot
: device handle (from spe4x155Add) : direction (symmetry) 0 = Drop 1 = Add : (pointer to) destination timeslot : (pointer to) allocated memory : source timeslot
Outputs Returns
psrcSlot
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_ARG
SPE4X155_ERR_INVALID_DEV SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
65
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
5.6
Section Overhead
The Section Overhead section provides functions to control and monitor the Section Overhead processing. Read / Write access is given to the section trace message (J0). This message is compared with a configurable reference and mismatches are reported. Section BIP-8 (B1) errors are accumulated in a counter that can be read and cleared. Section Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Section Overhead bytes.
Terminating Section Overhead: spe4x155SOHTermination
This function enables or disables the section termination of a particular STM-1. There are two possible modes: no section termination (SPE4X155_NO_TERM) and section termination (SPE4X155_TERM). Enabling section termination allows insertion of ZO and a section trace message in the transmit stream. Prototype Inputs
INT4 spe4x155SOHTermination (sSPE4X155_HNDL deviceHandle, UINT2 stm1, eSPE4X155_TERM mode) deviceHandle stm1 mode
: device Handle (from spe4x155Add) : STM-1 index : section termination mode, one of the following: SPE4X155_NO_TERM or
SPE4X155_TERM
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_ARG
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Reading and Setting the Section Trace Message (J0): spe4x155SectionTraceMsg
This function retrieves and sets the section trace message (J0) in the Sonet/SDH Section Trace Buffer. If this STM-1 is not configured for section termination, this function will have no effect on the section overhead. Note: It is the user's responsibility to ensure that the message pointer points to an area of memory large enough to hold the returned data. Prototype
INT4 spe4x155SectionTraceMsg(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 rw, UINT2 type,
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
66
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
UINT2 length, UINT1* pJ0)
Inputs
deviceHandle stm1 rw type
length
pJ0
: device handle (from spe4x155Add) : STM-1 index : read/write flag, write if zero : type of access 0 = tx section trace 1 = rx accepted section trace 2 = rx captured section trace 3 = rx expected section trace : length of the message 0 = 16 bytes 1 = 64 bytes : (pointer to) the section trace message : section trace message
Outputs Returns
pJ0
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_POLL_TIMEOUT
SPE4X155_ERR_INVALID_DEV SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Writing the Z0 Byte: spe4x155SOHWriteZ0
This function writes the Z0 byte into the transmit Section Overhead. If this STM-1 is not configured for section termination, this function will have no effect on the section overhead. Prototype Inputs
INT4 spe4x155SOHWriteZ0(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT1 Z0) deviceHandle stm1 Z0
: device handle (from spe4x155Add) : STM-1 index : Z0 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE, SPE4X155_INACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
67
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
None
Forcing Out-of-Frame: spe4x155SOHDiagOOF
When the enable flag is set, this function forces the Receive Section Overhead out-of-frame. When the enable flag is not set, the function resumes normal processing. Prototype Inputs
INT4 spe4x155SOHDiagOOF(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start / stop forcing OOF
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Errors in the Framing Bytes: spe4x155SOHDiagFB
This function enables the insertion of a single bit error continuously in the most significant bit (bit1) of the A1 Section Overhead framing byte. A1 bytes are set to 76H instead of F6H. Prototype Inputs
INT4 spe4x155SOHDiagFB(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start / stop error insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
68
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Forcing Section BIP-8 Errors: spe4x155SOHDiagB1
This function enables insertion of bit errors continuously in the B1 Section Overhead byte. Prototype Inputs
INT4 spe4x155SOHDiagB1(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start / stop error insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Loss-of-Signal: spe4x155SOHDiagLOS
This function enables insertion of zeros in the transmit outgoing stream. Prototype Inputs
INT4 spe4x155SOHDiagLOS(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start / stop error insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
69
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
5.7
Line Overhead
The Line Overhead section is responsible for configuring and monitoring the Line Overhead on both receive and transmit sides. Read / Write access is given to the APS bytes (K1 and K2) and most of the other overhead bytes. Line BIP-8 (B2) errors and REI are accumulated in counters that can be read and cleared. Line Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Line Overhead bytes. Additional functions are provided to configure the device to automatically insert line RDI and AIS.
Terminating Line Overhead: spe4x155LOHTermination
This function enables or disables the line termination of a particular STM-1. There are three possible modes: no line termination (SPE4X155_NO_TERM), line termination (SPE4X155_TERM) and line termination with automatic alarm insertion (SPE4X155_TERM_WITH_AUTO_INSERT). In termination mode, the K1 K2 values in device registers are inserted by the device, and in no termination mode the K1 K2 values are inserted by the overhead pins. In auto-insertion mode, line AIS is asserted on the DROP bus stream for signal degrade, signal failure, loss of frame, loss of signal, trace identifier mismatch, and trace identifier unstable alarms. Line RDI is asserted on the transmit stream for line AIS, signal degrade, signal failure, loss of frame, loss of signal, trace identifier mismatch, and trace identifier unstable alarms. As well, Line REI B2 error counts are inserted in the Z2/M1 byte on the transmit stream. Prototype Inputs
INT4 spe4x155LOHTermination (sSPE4X155_HNDL deviceHandle, UINT2 stm1, eSPE4X155_TERM mode) deviceHandle stm1 mode
: device Handle (from spe4x155Add) : STM-1 index : line termination mode, one of the following: SPE4X155_NO_TERM, SPE4X155_TERM or
SPE4X155_TERM_WITH_AUTO_INSERT
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_ARG
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
70
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Reading the Received K1 and K2 Bytes: spe4x155LOHReadK1K2
This function reads the K1 and K2 bytes from the received Line Overhead. Prototype
INT4 spe4x155LOHReadK1K2(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT1 *pK1, UINT1 *pK2) deviceHandle stm1 pK1 pK2 pK1 pK2
Inputs
: device handle (from spe4x155Add) : STM-1 index : (pointer to) K1 byte : (pointer to) K2 byte : K1 byte read : K2 byte read
Outputs
Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Writing the Transmitted K1 and K2 Bytes: spe4x155LOHWriteK1K2
This function writes the K1 and K2 bytes into the transmit line overhead. If this STM-1 is not configured for line termination, this function will have no effect on the line overhead. Prototype Inputs
INT4 spe4x155LOHWriteK1K2(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT1 K1, UINT1 K2) deviceHandle stm1 K1 K2
: device handle (from spe4x155Add) : STM-1 index : K1 byte to write : K2 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
71
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Reading the S1 Byte: spe4x155LOHReadS1
This function read the S1 byte from the receive Line Overhead. Prototype Inputs
INT4 spe4x155LOHReadS1(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT1 *pS1)) deviceHandle stm1 pS1 pS1
: device handle (from spe4x155Add) : STM-1 index : (pointer to) allocated memory : received S1 byte
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Writing the S1 Byte: spe4x155LOHWriteS1
This function writes the S1 byte into the transmit Line Overhead. Prototype Inputs
INT4 spe4x155LOHWriteS1(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT1 S1) deviceHandle stm1 S1
: device handle (from spe4x155Add) : STM-1 index : S1 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
72
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Inserting Line Remote Defect Indication: spe4x155LOHInsertLineRDI
This function enables the insertion of a transmit line remote defect indication (RDI). The Line RDI is inserted by transmitting the code 110 in bit positions 6, 7, and 8 of the K2 byte. Prototype Inputs
INT4 spe4x155LOHInsertLineRDI(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start / stop Line RDI insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Line BIP-8 Errors: spe4x155LOHDiagB2
This function enables the insertion of bit errors continuously in each of the line BIP-8 bytes (B2 bytes). Prototype Inputs
INT4 spe4x155LOHDiagB2(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
: device handle (from spe4x155Add) : STM-1 index : flag to start / stop B2 error insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
73
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Inserting Line AIS: spe4x155LOHInsertLineAIS
When the enable flag is set, this function forces a Line-AIS insertion. When the enable flag is not set, this function resumes normal processing. Prototype Inputs
INT4 spe4x155LOHInsertLineAIS(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable None
: device handle (from spe4x155Add) : STM-1 index : flag to start / stop Line-AIS insertion
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Configuring Signal Fail and Signal Degrade: spe4x155LOHCfgSFSD
This function configures the Signal Fail and Signal Degrade bit error rate monitoring capabilities. Prototype
INT4 spe4x155LOHCfgSFSD(sSPE4X155_HNDL deviceHandle, UINT2 stm1, sSPE4X155_CFG_SFSD *pcfgSF, sSPE4X155_CFG_SFSD *pcfgSD) deviceHandle stm1 pcfgSF pcfgSD None
Inputs
: device handle (from spe4x155Add) : STM-1 index : SF configuration : SD configuration
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
74
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
5.8
Path Overhead
The Path Overhead section configures and monitors the Path Overhead on both receive and transmit sides. Read / Write access is given to the path trace message (J1) and the path signal label (C2). Both are compared with a configurable reference and mismatches are reported. Path BIP-8 (B3) errors and REI are accumulated in a counter that can be read and cleared. Path Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Path Overhead bytes. Additional functions are provided to configure the device to automatically insert path RDI, path enhanced RSI and path AIS.
Path Trace Message Retrieving and Setting the Path Trace Messages: spe4x155PathTraceMsg
This function retrieves and sets the current path trace message (J1) in the Sonet/SDH Path Trace Buffer. Note: It is the user's responsibility to make sure that the message pointer points to an area of memory large enough to hold the returned data. If this STM-1, AU-3 is not configured for TPOH termination, this function will have no effect on the path overhead. Prototype
INT4 spe4x155PathTraceMsg(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 rw, UINT2 type, UINT2 length, UINT1* pJ1) deviceHandle stm1 au3 rw type length
Inputs
pJ1
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : read/write flag, write if zero : type of access : length of the message 0 = 16 bytes 1 = 64 bytes : (pointer to) the path trace message : updated path trace message
Outputs Returns
pJ1
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_POLL_TIMEOUT
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
75
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Receive Path Overhead (RPOH) Terminating Receive Path Overhead: spe4x155RPOHTermination
This function enables or disables the path termination of a particular (STM-1, AU3) slice. There are two possible modes: no path termination (SPE4X155_NO_TERM), and path termination with automatic alarm insertion (SPE4X155_TERM_WITH_AUTO_INSERT). In automatic alarm insertion mode, on detection of loss of pointer, path alarm indication signal, loss of signal, loss of frame, line alarm indication signal, unequipped, path signal label unstable, path signal label mismatch, path trace identifier unstable, and path trace identifier mismatch alarms, path AIS is inserted on the DROP bus, plus RDI and Enhanced RDI are inserted in the transmit stream. On detection of received B3 errors, the path REI count is inserted in the transmit G1 byte. Prototype
INT4 spe4x155RPOHTermination(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, eSPE4X155_TERM mode) deviceHandle stm1 au3 mode
Inputs
: device Handle (from spe4x155Add) : STM-1 index : AU-3 index : path termination mode, one of the following: SPE4X155_NO_TERM or
SPE4X155_TERM_WITH_AUTO_INSERT
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_ARG
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Path Signal Label: spe4x155RPOHPathSignalLabel
This function retrieves and sets the expected, as well, as retrieves the captured path signal label (C2). Prototype
spe4x155RPOHPathSignalLabel(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 rw, UINT2 type, UINT1* pPSL) deviceHandle stm1 au3 rw
Inputs
: device Handle (from spe4x155Add) : STM-1 index : AU-3 index : read/write flag, write if zero
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
76
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
type
pPSL
: type of access 1 = received PSL 2 = expected PSL : (pointer to) path signal label : updated path signal label
Outputs Returns
pPSL
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Loss-of-Pointer: spe4x155RPOHDiagLOP
This function forces the downstream pointer processing to enter the Loss of Pointer (LOP) state. It does so by using the Diagnose LOP functionality activiated by setting the DLOP bit in the RTAL control register. Prototype
INT4 spe4x155RPOHDiagLOP(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop NDF inversion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Pointer Justification: spe4x155RPOHDiagPJ
This function diagnoses the downstream pointer processing elements so there are correct reactions to pointer justification events. The function forces positive or negative justification events, or disables the generation of any pointer justification element.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
77
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Prototype
INT4 spe4x155RPOHDiagPJ(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable, INT1 type) deviceHandle stm1 au3 enable type
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop diagnostic : type of pointer justification event: 0 = no pointer justification -1 = negative pointer justification +1 = positive pointer justification
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Errors in the H4 Byte: spe4x155RPOHDiagH4
This function enables the inversion of the multiframe indicator (H4) byte in the DROP bus. An inversion forces an out-of-multiframe alarm in the downstream circuitry. This can only occur when the SPE (VC) is used to carry virtual tributary (VT) or tributary unit (TU) based payloads. Prototype Inputs
INT4 spe4x155RPOHDiagH4(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3 enable
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop H4 inversion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
78
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Forcing Tributary Path AIS: spe4x155RPOHInsertTUAIS
This function enables the insertion of tributary path AIS on the DROP bus for VT1.5 (TU11), VT2 (TU12), VT3 and VT6 (TU2) payloads. Columns in the DROP bus carrying tributary traffic are set to all ones. The pointer bytes (H1, H2, and H3), the Path Overhead column, and the fixed stuff columns remain unaffected. Note: This is not applicable for TU3 tributary payloads. Prototype
INT4 spe4x155RPOHInsertTUAIS(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop TUAIS
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Path AIS: spe4x155RPOHInsertPAIS
This function enables the insertion of the path alarm indication signal (PAIS) on the DROP bus. The synchronous payload envelope and the pointer bytes (H1 - H3) are set to all ones. Prototype
INT4 spe4x155RPOHInsertPAIS(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop PAIS insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
79
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Transmit Path Overhead (TPOH) Terminating Transmit Path Overhead: spe4x155TPOHTermination
This function enables or disables the path termination of a particular (STM-1, AU3) slice. There are three possible modes: no path termination (SPE4X155_NO_TERM), path termination (SPE4X155_TERM) and path termination with automatic alarm insertion (SPE4X155_TERM_WITH_AUTO_INSERT). If selected, automatic error insertion in G1 is performed. In path termination mode, device insertion of the path trace message, REI, C2, F2, Z3, Z4, and N1/Z5 is enabled. In alarm auto-insertion mode, path AIS is inserted in the transmit stream on detection of LOP and path AIS on the ADD bus, as well as for detection of concatenated LOP and PAIS detection on AU-3 #2 and #3 in a concatenated stream. Prototype
INT4 spe4x155TPOHTermination(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, eSPE4X155_TERM mode) deviceHandle stm1 au3 mode
Inputs
: device Handle (from spe4x155Add) : STM-1 index : AU-3 index : path termination mode, one of the following: SPE4X155_NO_TERM, SPE4X155_TERM or
SPE4X155_TERM_WITH_AUTO_INSERT
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_ARG
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Path BIP-8 Errors: spe4x155TPOHDiagB3
This function enables the inversion of the path BIP-8 byte (B3) in the transmit stream. The B3 byte is inverted causing the insertion of eight path BIP-8 errors per frame. Prototype
INT4 spe4x155TPOHDiagB3(sSPE4X155_HNDL
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
80
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable)
Inputs
deviceHandle stm1 au3 enable
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop B3 inversion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing a Pointer Value: spe4x155TPOHForceTxPtr
This function enables the insertion of the pointer value passed in argument into the H1 and H2 bytes of the transmit stream. As a result, the upstream payload mapping circuitry and a valid SPE can continue functioning and generating normally. Prototype
INT4 spe4x155TPOHForceTxPtr(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable, UINT2 aptr) deviceHandle stm1 au3 enable aptr
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop generation : pointer value to insert in (H1, H2)
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
81
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Writing the New Data Flag Bits: spe4x155TPOHInsertNDF
This function enables the insertion of the passed new data flag bits (NDF[3:0]) in the NDF bit positions. Prototype
INT4 spe4x155TPOHInsertNDF(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable, UINT1 ndf) deviceHandle stm1 au3 enable ndf
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop NDF insertion : NDF value
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Writing the J1 Byte: spe4x155TPOHWriteJ1
This function writes the J1 byte into the Transmit Path Overhead. Prototype Inputs
INT4 spe4x155TPOHWriteJ1(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 J1) deviceHandle stm1 au3 J1
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : J1 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
82
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Writing the C2 Byte: spe4x155TPOHWriteC2
This function writes the C2 byte into the Transmit Path Overhead. If this (STM-1, AU3) is not configured for path termination, this function will have no effect on the path overhead. Prototype Inputs
INT4 spe4x155TPOHWriteC2(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 C2) deviceHandle stm1 au3 C2
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : C2 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Writing the Path Remote Error Indication Count: spe4x155TPOHInsertPREI
This function inserts the path remote error indication count passed in argument inside the path status byte. If this (STM-1, AU3) is not configured for path termination, this function will have no effect on the path overhead. Prototype
INT4 spe4x155TPOHInsertPREI(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 PREI) deviceHandle stm1 au3 prei
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : PREI value
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE, SPE4X155_INACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
83
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
None
Writing the F2 Byte: spe4x155TPOHWriteF2
This function writes the F2 byte into the Transmit Path Overhead. If this (STM-1, AU3) is not configured for path termination, this function will have no effect on the path overhead. Prototype Inputs
INT4 spe4x155TPOHWriteF2(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 F2) deviceHandle stm1 au3 F2
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : F2 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Writing the Z3 Byte: spe4x155TPOHWriteZ3
This function writes the Z3 byte into the Transmit Path Overhead. If this (STM-1, AU3) is not configured for path termination, this function will have no effect on the path overhead. Prototype Inputs
INT4 spe4x155TPOHWriteZ3(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 Z3) deviceHandle stm1 au3 Z3
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : Z3 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE, SPE4X155_INACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
84
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
None
Writing the Z4 Byte: spe4x155TPOHWriteZ4
This function writes the Z4 byte into the Transmit Path Overhead. If this (STM-1, AU3) is not configured for path termination, this function will have no effect on the path overhead. Prototype Inputs
INT4 spe4x155TPOHWriteZ4(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 Z4) deviceHandle stm1 au3 Z4
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : Z4 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Writing the N1/Z5 Byte: spe4x155TPOHWriteZ5
This function writes the N1/Z5 byte into the Transmit Path Overhead. If this (STM-1, AU3) is not configured for path termination, this function will have no effect on the path overhead. Prototype Inputs
INT4 spe4x155TPOHWriteZ5(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 Z5) deviceHandle stm1 au3 Z5
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : Z5 byte to write
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE, SPE4X155_INACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
85
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
None
Controlling Pointer Justification: spe4x155TPOHDiagPJ
This function diagnoses the downstream pointer processing elements for correct reaction to pointer justification events. It can force positive or negative stuff justification events, or disable the generation of any pointer justification element. Prototype
INT4 spe4x155TPOHDiagPJ(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable, INT1 type) deviceHandle stm1 au3 enable type
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop diagnostic : type of pointer justification event: 0 for no pointer justification -1 for negative +1 for positive
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Multiframe Error: spe4x155TPOHDiagH4
This function enables the inversion of the multiframe indicator (H4) byte in the TRANSMIT stream. This forces an out of multiframe alarm in the downstream circuitry when the SPE (VC) is used to carry virtual tributary (VT) or tributary unit (TU) based payloads. Prototype
INT4 spe4x155TPOHDiagH4(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop H4 inversion
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
86
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Tributary Path AIS: spe4x155TPOHInsertTUAIS
This function enables the insertion of tributary path AIS in the transmit stream for VT1.5 (TU11), VT2 (TU12), VT3 and VT6 (TU2) payloads. Columns in the transmit stream carrying tributary traffic are set to all ones. The pointer bytes (H1, H2, and H3); the Path Overhead column; and the fixed stuff columns are unaffected. Note: This is not applicable for TU3 tributary payloads. Prototype
INT4 spe4x155TPOHInsertTUAIS(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : flag to start/stop TUAIS insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Path AIS: spe4x155TPOHInsertPAIS
This function enables the insertion of the path alarm indication signal (PAIS) in the transmit stream. The synchronous payload envelope and the pointer bytes (H1 - H3) are set to all ones. Prototype
INT4 spe4x155TPOHInsertPAIS(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle
Inputs
: device handle (from spe4x155Add)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
87
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
stm1 au3 enable
: STM-1 index : AU-3 index : flag to start/stop PAIS insertion
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
5.9
DROP / ADD Bus PRBS Generator and Monitor (DPGM / APGM)
DROP Bus PRBS Generator and Monitor (DPGM) Configuring the PRBS Generator: spe4x155DPGMGenCfg
This function fully configures the Drop bus PRBS generator. Prototype
INT4 spe4x155DPGMGenCfg(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_CFG_PRBS *pcfgPrbs) deviceHandle stm1 au3 pcfgPrbs
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : PRBS configuration structure
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
88
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Configuring the PRBS Monitor: spe4x155DPGMMonCfg
This function fully configures the Drop bus PRBS monitor. Prototype
INT4 spe4x155DPGMMonCfg(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_CFG_PRBS *pcfgPrbs) deviceHandle stm1 au3 pcfgPrbs
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : PRBS configuration structure
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Generation of a New PRBS: spe4x155DPGMGenRegen
This function reinitializes the generator LFSR and regenerates the Pseudo Random Bit Sequence (PRBS) from the known reset state. The LFSR is dependent on the sequence number. This automatically forces all slaves to reset at the same time. Prototype Inputs
INT4 spe4x155DPGMGenRegen(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
: device handle (from spe4x155Add) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
89
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Forcing Bit Errors: spe4x155DPGMGenForceErr
This function forces bit errors in the inserted Pseudo Random Bit Sequence (PRBS). Thereafter, the MSB of the PRBS is inverted, inducing a single bit error. Prototype Inputs
INT4 spe4x155DPGMGenForceErr(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
: device handle (from spe4x155Add) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing a Resynchronization: spe4x155DPGMMonResync
This function forces the resynchronization of the monitor to the incoming Pseudo Random Bit Sequence (PRBS). The monitor will go out of synchronization and begin re-synchronizing the incoming PRBS payload. This will automatically force all slaves to resynchronize at the same time. Prototype Inputs
INT4 spe4x155DPGMMonResync(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
: device handle (from spe4x155Add) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
90
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
ADD Bus PRBS Generator and Monitor (APGM) Configuring the PRBS Generator: spe4x155APGMGenCfg
This function fully configures the Add bus PRBS generator. Prototype
INT4 spe4x155APGMGenCfg(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_CFG_PRBS *pcfgPrbs) deviceHandle stm1 au3 pcfgPrbs
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : PRBS configuration structure
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Configuring the PRBS Monitor: spe4x155APGMMonCfg
This function fully configures the Add bus PRBS monitor. Prototype
INT4 spe4x155APGMMonCfg(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_CFG_PRBS *pcfgPrbs) deviceHandle stm1 au3 pcfgPrbs
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : PRBS configuration structure
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE, SPE4X155_INACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
91
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
None
Forcing Generation of a New PRBS: spe4x155APGMGenRegen
This function reinitializes the generator LFSR and regenerates the Pseudo Random Bit Sequence (PRBS) from the known reset state. The LFSR is dependent on the sequence number. This automatically forces all slaves to reset at the same time. Prototype Inputs
INT4 spe4x155APGMGenRegen(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
: device handle (from spe4x155Add) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Forcing Bit Errors: spe4x155APGMGenForceErr
This function forces bit errors in the inserted Pseudo Random Bit Sequence (PRBS). Thereafter, the MSB of the PRBS is inverted, inducing a single bit error. Prototype Inputs
INT4 spe4x155APGMGenForceErr(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
: device handle (from spe4x155Add) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
92
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Forcing a Resynchronization: spe4x155APGMMonResync
This function forces the resynchronization of the monitor to the incoming Pseudo Random Bit Sequence (PRBS). The monitor will go out of synchronization and begin re-synchronizing the incoming PRBS payload. This will automatically force all slaves to resynchronize at the same time. Prototype Inputs
INT4 spe4x155APGMMonResync(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
: device handle (from spe4x155Add) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
5.10 Interrupt Service Functions
This Section describes interrupt-service functions that perform the following tasks: * * * Set, get and clear the interrupt enable mask Read and process the interrupt-status registers Poll and process the interrupt-status registers
See page 27 for an explanation of our interrupt servicing architecture.
Configuring ISR Processing: spe4x155ISRConfig
This function allows the user to configure how ISR processing is to be handled: polling (SPE4X155_POLL_MODE) or interrupt driven (SPE4X155_ISR_MODE). If polling is selected, the user is responsible for calling periodically spe4x155Poll to collect exception data form the device. Prototype
INT4 spe4x155ISRConfig(sSPE4X155_HNDL deviceHandle, UINT2 mode)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
93
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Inputs
deviceHandle mode
: device handle (from spe4x155Add) : mode of operation
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_MODE SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Getting the Interrupt Status Mask: spe4x155GetMask
This function returns the contents of the interrupt mask registers of the SPECTRA-4x155 device. Prototype Inputs
INT4 spe4x155GetMask(sSPE4X155_HNDL deviceHandle, sSPE4X155_MASK *pmask) deviceHandle pmask pmask
: device handle (from spe4x155Add) : (pointer to) mask structure : (pointer to) updated mask structure
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Setting the Interrupt Enable Mask: spe4x155SetMask
This function sets the contents of the interrupt mask registers of the SPECTRA-4x155 device. Prototype Inputs
INT4 spe4x155SetMask(sSPE4X155_HNDL deviceHandle, sSPE4X155_MASK *pmask) deviceHandle pmask
: device handle (from spe4x155Add) : (pointer to) mask structure
Outputs Returns
None Success = SPE4X155_SUCCESS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
94
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
May change the operation of the ISR / DPR
Clearing the Interrupt Enable Mask: spe4x155ClearMask
This function clears individual interrupt bits and registers in the SPECTRA-4x155 device. Any bits that are set in the passed structure are cleared in the associated SPECTRA-4x155 registers. Prototype Inputs
INT4 spe4x155ClearMask(sSPE4X155_HNDL deviceHandle, sSPE4X155_MASK *pmask) deviceHandle pmask
: device handle (from spe4x155Add) : (pointer to) mask structure
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
May change the operation of the ISR / DPR
Polling the Interrupt Status Registers: spe4x155Poll
This function commands the driver to poll the interrupt registers in the device. The call will fail unless the device was initialized (via spe4x155Init) or configured (via spe4x155ISRConfig) into polling mode. Prototype Inputs Outputs Returns
INT4 spe4x155Poll(sSPE4X155_HNDL deviceHandle) deviceHandle
: device handle (from spe4x155Add)
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_MODE SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
95
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
None
Interrupt-Service Routine: spe4x155ISR
This function reads the state of the interrupt registers in the SPECTRA-4x155 and stores them in an ISV. Performs whatever functions are needed to clear the interrupt, from simply clearing bits to complex functions. This routine is called by the application code, from within sysSpe4x155ISRHandler. If ISR mode is configured all interrupts that were detected are disabled and the ISV is returned to the application. Note that the application is then responsible for sending this buffer to the DPR task. If polling mode is selected, no ISV is returned to the application and the DPR is called directly with the ISV. Prototype Inputs Outputs Returns Valid States Side Effects
void * spe4x155ISR(sSPE4X155_HNDL deviceHandle) deviceHandle
: device handle (from spe4x155Add)
None (pointer to) ISV buffer (to send to the DPR) or NULL (pointer)
SPE4X155_ACTIVE
None
Deferred-Processing Routine: spe4x155DPR
This function acts on data contained in the passed ISV, allocates one or more DPV buffers (via sysSpe4x155DPVBufferGet) and invokes one or more callbacks (if defined and enabled). This routine is called by the application code, within sysSpe4x155DPRTask. Note that the callbacks are responsible for releasing the passed DPV. It is recommended that it be done as soon as possible to avoid running out of DPV buffers. Prototype Inputs Outputs Returns Valid States Side Effects
void spe4x155DPR(void *pisv) pisv
: (pointer to) ISV buffer
None None
SPE4X155_ACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
96
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Setting the Thresholds for Callbacks: spe4x155SetThresh
This function sets the number of events that must be received (thresholds) before those events are reported via the callbacks. Prototype Inputs
INT4 spe4x155SetThresh(sSPE4X155_HNDL deviceHandle, sSPE4X155_MASK *pthreshold) deviceHandle pthreshold
: device handle (from spe4x155Add) : (pointer to) threshold structure
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Getting the Thresholds for Callbacks: spe4x155GetThresh
This function sets the number of events that must be received (thresholds) before those events are reported via the callbacks. Prototype Inputs
INT4 spe4x155GetThresh(sSPE4X155_HNDL deviceHandle, sSPE4X155_MASK *pthreshold) deviceHandle pthreshold pthreshold
: device handle (from spe4x155Add) : (pointer to) allocated memory : threshold structure
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
97
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Getting the Event Counters: spe4x155GetThreshCntr
This function returns the number of events that have occurred while the thresholds have not been reached. Prototype Inputs
INT4 spe4x155SetThreshCntr(sSPE4X155_HNDL deviceHandle, sSPE4X155_MASK *pthreshCntr) deviceHandle pthreshold pthreshold
: device handle (from spe4x155Add) : (pointer to) allocated memory : event counters
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
5.11 Alarm, Status and Statistics Functions
Configuring the Device Statistics: spe4x155CfgStats
This function configures the device counts. Prototype Inputs
INT4 spe4x155CfgStats(sSPE4X155_HNDL deviceHandle, sSPE4X155_CFG_CNT cfgCnt) deviceHandle cfgCnt
: device handle (from spe4x155Add) : counters configuration block
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ACTIVE, SPE4X155_INACTIVE
Valid States Side Effects
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
98
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Statistics Collection Routine: spe4x155GetCnt
This function retrieves all the device counts. This routine should be called by the application code, in the context of a task. It is the user's responsibility to ensure that this function is called often enough to prevent the device counts from saturating. Prototype Inputs
INT4 spe4x155GetCnt(sSPE4X155_HNDL deviceHandle, sSPE4X155_STAT_CNT *pcnt) deviceHandle pcnt pcnt
: device handle (from spe4x155Add) : (pointer to) allocated memory : current device counts
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ACTIVE
Valid States Side Effects
None
Getting Counter for SOH Block: spe4x155GetCntSOH
This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype
INT4 spe4x155GetCntSOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, sSPE4X155_STAT_CNT_SOH *pcntSOH) deviceHandle stm1 pcntSOH pcntSOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : (pointer to) allocated memory : current device counts
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
99
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Getting Counters for LOH Block: spe4x155GetCntLOH
This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype
INT4 spe4x155GetCntLOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, sSPE4X155_STAT_CNT_LOH *pcntLOH) deviceHandle stm1 pcntLOH pcntLOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : (pointer to) allocated memory : current device counts
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
None
Getting Counters for RPOH Block: spe4x155GetCntRPOH
This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype
INT4 spe4x155GetCntRPOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_STAT_CNT_RPOH *pcntRPOH) deviceHandle stm1 au3 pcntRPOH pcntRPOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : (pointer to) allocated memory : current device counts
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE,
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
100
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Getting Counters for TPOH Block: spe4x155GetCntTPOH
This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype
INT4 spe4x155GetCntTPOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_STAT_CNT_TPOH *pcntTPOH) deviceHandle stm1 au3 pcntTPOH pcntTPOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : (pointer to) allocated memory : current device counts
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE, SPE4X155_INACTIVE
None
Getting Counters for Pointer Justifications: spe4x155GetCntPJ
This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype
UINT4 statSpe4x155GetCntPJ(sSPE4X155_DDB *pddb, UINT2 stm1, UINT2 au3, sSPE4X155_STAT_CNT_PJ *pcntPJ) deviceHandle stm1 au3 pcntPJ pcntPJ
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : (pointer to) allocated memory : current device counts
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE,
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
101
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
None
Getting Current Status: spe4x155GetStatus
This function retrieves the current alarm status by reading all the alarm status registers. It is the user's responsibility to ensure that the passed structure points to an area of memory large enough to hold a copy of the status structure. Prototype Inputs
INT4 spe4x155GetStatus(sSPE4X155_HNDL deviceHandle, sSPE4X155_STATUS *palm) deviceHandle palm palm
: device handle (from spe4x155Add) : (pointer to) allocated memory : current alarm status
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_ARG
Valid States Side Effects
SPE4X155_ACTIVE
None
Getting Current Status for IO block: spe4x155GetStatusIO
This function retrieves the clock activity from the status registers. Prototype Inputs
INT4 spe4x155GetStatusIO(sSPE4X155_HNDL deviceHandle, sSPE4X155_STATUS_IO *palmIO) deviceHandle palmIO palmIO
: device handle (from spe4x155Add) : (pointer to) allocated memory : current alarm status
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_INVALID_ARG
Valid States Side Effects
SPE4X155_ACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
102
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Getting Current Alarm Status for SOH block: spe4x155GetStatusSOH
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spe4x155GetStatusSOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, sSPE4X155_STATUS_SOH *palmSOH) deviceHandle stm1 palmSOH palmSOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : (pointer to) allocated memory : current alarm status
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
None
Getting Current Alarm Status for LOH block: spe4x155GetStatusLOH
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spe4x155GetStatusLOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, sSPE4X155_STATUS_LOH *palmLOH) deviceHandle stm1 palmLOH palmLOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : (pointer to) allocated memory : current alarm status
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
103
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Getting Current Alarm Status for RPOH block: spe4x155GetStatusRPOH
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spe4x155GetStatusRPOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_STATUS_RPOH *palmRPOH) deviceHandle stm1 au3 palmRPOH palmRPOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : (pointer to) allocated memory : current alarm status
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
None
Getting Current Alarm Status for TPOH block: spe4x155GetStatusTPOH
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spe4x155GetStatusTPOH(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE4X155_STATUS_TPOH *palmTPOH) deviceHandle stm1 au3 palmTPOH palmTPOH
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : (pointer to) allocated memory : current alarm status
Outputs Returns
Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
104
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
5.12 Device Diagnostics
Testing Register Accesses: spe4x155DiagTestReg
This function verifies the hardware access to the device registers by writing and reading back values. Prototype Inputs Outputs Returns
INT4 spe4x155DiagTestReg(sSPE4X155_HNDL deviceHandle) deviceHandle
: device handle (from spe4x155Add)
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_PRESENT
Valid States Side Effects
None
Clearing and Setting a Line Loopback: spe4x155DiagLineLoop
This function clears and sets a Line Loopback (SLLE=1). The spe4x155DiagLineLoop connects the high speed receive data and clock to the high speed transmit data and clock, and can be used for line side investigations (including clock recovery and clock synthesis). While in this mode, the entire receive path is operating normally. Note: It is up to the user to perform any tests on the looped data.
INT4 spe4x155DiagLineLoop(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
Prototype Inputs
: device handle (from spe4x155Add) : STM-1 index : sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States
SPE4X155_ACTIVE
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
105
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Side Effects
Will inhibit the flow of active data
Clearing and Setting a Serial Loopback: spe4x155DiagSerialLoop
This function clears and sets a Serial Diagnostic Loopback (SDLE=1). It connects the high speed transmit data and clock to the high speed receive data and clock. While in this mode, the entire transmit path is operating normally and data is transmitted on the TXD+/- outputs. Note: It is up to the user to perform any tests on the looped data.
INT4 spe4x155DiagSerialLoop(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
Prototype Inputs
: device handle (from spe4x155Add) : STM-1 index : sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
Will inhibit the flow of active data
Clearing and Setting a Parallel Loopback: spe4x155DiagParaLoop
This function clears and sets a parallel diagnostic loopback (PDLE=1). It connects the byte wide transmit data and clock to the byte wide receive data and clock. While in this mode, the entire transmit path is operating normally and data is transmitted on the TXD+/- outputs. Note: It is up to the user to perform any tests on the looped data.
INT4 spe4x155DiagParaLoop(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 enable) deviceHandle stm1 enable
Prototype Inputs
: device handle (from spe4x155Add) : STM-1 index : sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
106
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
Will inhibit the flow of active data
Clearing and Setting a System-Side Loopback: spe4x155DiagSysSideLineLoop
This function clears and sets a system-side line loopback (SLLBEN=1). It connects the STS-1 (STM-0/AU3) or equivalent receive stream from the Receive Telecom bus Aligner (RTAL) of the associated RPPS to the Transmit Telecom bus Aligner (TTAL) of the corresponding TPPS. This mode can be used for line side investigations (including clock recovery and clock synthesis) as well as path processing investigations. While in this mode, the entire receive path is operating normally. SPECTRA-4x155 may be configured to support the system-side line loopback of up to twelve STS-1 (STM-0/AU3) or equivalent receive streams. Note: It is up to the user to perform any tests on the looped data.
INT4 spe4x155DiagSysSideLineLoop(sSPE4X155_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Prototype
Inputs
: device handle (from spe4x155Add) : STM-1 index : AU-3 index : sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE4X155_SUCCESS Failure = SPE4X155_ERR_INVALID_DEV
SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_DEVICE_STATE
Valid States Side Effects
SPE4X155_ACTIVE
Will inhibit the flow of active data
5.13 Callback Functions
The SPECTRA-4x155 driver has the capability to callback to functions within the user code when certain events occur. These events and their associated callback routine declarations are detailed below. There is no user code action that is required by the driver for these callbacks - the user is free to implement these callbacks in any manner or else they can be deleted from the driver.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
107
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
The names given to the callback functions are given as examples only. The addresses of the callback functions invoked by the spe4x155DPR function are passed during the spe4x155Init call (inside a DIV). However the user shall use the exact same prototype. The application is left responsible for releasing the passed DPV as soon as possible (to avoid running out of DPV buffers) by calling sysSpe4x155DPVBufferRtn either within the callback function or later inside the application code.
Notifying the Application of IO Events: cbackSpe4x155IO
This callback function is provided by the user and is used by the DPR to report significant IO section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: the callback function's addresses are passed to the driver doing the spe4x155Init call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs
void cbackSpe4x155IO(sSPE4X155_USR_CTXT usrCtxt, void *pdpv) usrCtxt pdpv
: user context (from spe4x155Add) : (pointer to) DPV that describes this event
Outputs Returns Valid States Side Effects
None None
SPE4X155_ACTIVE
None
Notifying the Application of SOH Events: cbackSpe4x155SOH
This callback function is provided by the user and is used by the DPR to report significant SOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: the callback function's addresses are passed to the driver doing the spe4x155Init call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs
void cbackSpe4x155SOH(sSPE4X155_USR_CTXT usrCtxt, void *pdpv) usrCtxt pdpv
: user context (from spe4x155Add) : (pointer to) DPV that describes this
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
108
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
event Outputs Returns Valid States Side Effects None None
SPE4X155_ACTIVE
None
Notifying the Application of LOH Events: cbackSpe4x155LOH
This callback function is provided by the user and is used by the DPR to report significant LOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: the callback function's addresses are passed to the driver doing the spe4x155Init call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs
void cbackSpe4x155LOH(sSPE4X155_USR_CTXT usrCtxt, void *pdpv) usrCtxt pdpv
: user context (from spe4x155Add) : (pointer to) DPV that describes this event
Outputs Returns Valid States Side Effects
None None
SPE4X155_ACTIVE
None
Notifying the Application of RPOH Events: cbackSpe4x155RPOH
This callback function is provided by the user and is used by the DPR to report significant RPOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: the callback function's addresses are passed to the driver doing the spe4x155Init call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype
void cbackSpe4x155RPOH(sSPE4X155_USR_CTXT usrCtxt, void *pdpv)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
109
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Inputs
usrCtxt pdpv
: user context (from spe4x155Add) : (pointer to) DPV that describes this event
Outputs Returns Valid States Side Effects
None None
SPE4X155_ACTIVE
None
Notifying the Application of TPOH Events: cbackSpe4x155TPOH
This callback function is provided by the user and is used by the DPR to report significant TPOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: the callback function's addresses are passed to the driver doing the spe4x155Init call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs
void cbackSpe4x155TPOH(sSPE4X155_USR_CTXT usrCtxt, void *pdpv) usrCtxt pdpv
: user context (from spe4x155Add) : (pointer to) DPV that describes this event
Outputs Returns Valid States Side Effects
None None
SPE4X155_ACTIVE
None
Notifying the Application of DPGM Events: cbackSpe4x155DPGM
This callback function is provided by the user and is used by the DPR to report significant DPGM section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: the callback function's addresses are passed to the driver doing the spe4x155Init call. If the address of the callback function was passed as a NULL at initialization no callback will be made.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
110
Spectra-4x155 (PM5316) Driver Manual Application Programming Interface
Prototype Inputs
void cbackSpe4x155DPGM(sSPE4X155_USR_CTXT usrCtxt, void *pdpv) usrCtxt pdpv
: user context (from spe4x155Add) : (pointer to) DPV that describes this event
Outputs Returns Valid States Side Effects Pseudocode
None None
SPE4X155_ACTIVE
None IF GEN_SIG interrupt occurred call spe4x155DPGMGenRegen ...Application specific behavior...
Notifying the Application of APGM Events: cbackSpe4x155APGM
This callback function is provided by the user and is used by the DPR to report significant APGM section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: the callback function's addresses are passed to the driver doing the spe4x155Init call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs
void cbackSpe4x155APGM(sSPE4X155_USR_CTXT usrCtxt, void *pdpv) usrCtxt pdpv
: user context (from spe4x155Add) : (pointer to) DPV that describes this event
Outputs Returns Valid States Side Effects
None None
SPE4X155_ACTIVE
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
111
Spectra-4x155 (PM5316) Driver Manual Hardware Interface
6
HARDWARE INTERFACE
The SPECTRA-4x155 driver interfaces directly with the user's hardware. In this section, a listing of each point of interface is shown, along with a declaration and any specific porting instructions. It is the responsibility of the user to connect these requirements into the hardware, either by defining a macro or by writing a function for each item listed. Care should be taken when matching parameters and return values.
6.1
Device I/O
Reading from a Device Register: sysSpe4x155Read
sysSpe4x155Read is the most basic hardware connection and reads the contents of a specific register location. This macro should be UINT1 oriented and should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function.
Format Prototype Inputs
#define sysSpe4x155Read(base, offset) UINT1 sysSpe4x155Read(void *base, UINT2 offset) base offset
: base address of device being accessed : offset to the memory location as it appears in the hardware data-sheet
Outputs Returns
None value read from the addressed register location
Writing to a Device Register: sysSpe4x155Write
sysSpe4x155Write is the most basic hardware connection and writes the supplied value to the specific register location. This macro should be UINT1 oriented and should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function.
Format Prototype Inputs
#define sysSpe4x155Write(base, offset, data) UINT1 sysSpe4x155Write(void *base, UINT2 offset, UINT2 data) base offset data
: base address of device being accessed : offset to the memory location as it appears in the hardware data-sheet : data to be written
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
112
Spectra-4x155 (PM5316) Driver Manual Hardware Interface
Outputs Returns
None Value written to the addressed register location
Polling a Bit: sysSpe4x155PollBit
This function simply polls a register masked data until it is zero or times out. Format Prototype Inputs
#define sysSpe4x155PollBit(base, offset, mask) INT4 sysSpe4x155PollBit(void *base, UINT2 offset, UINT1 mask) base offset mask
: base address of device being accessed : offset to the memory location as it appears in the hardware data-sheet : mask to apply to byte read
Outputs Returns
None Success = 0 Failure =
6.2
System-Specific Interrupt Servicing
The porting of an Interrupt-Service Routine (ISR) between platforms is a rather difficult task. There are many different implementations of these hardware level routines. In this driver, the user is responsible for installing an interrupt handler (sysSpe4x155ISRHandler) in the interrupt vector table of the system processor. This handler shall call spe4x155ISR for each device that has interrupt servicing enabled, to perform the ISR related housekeeping required by each device. During execution of the API function spe4x155ModuleStart / spe4x155ModuleStop the driver informs the application that it is time to install / uninstall this shell via sysSpe4x155ISRHandlerInstall / sysSpe4x155ISRHandlerRemove, that needs to be supplied by the user. Note: A device can be initialized with ISR disabled. In that mode, the user should periodically invoke a provided `polling' routine (spe4x155Poll) that in turn calls spe4x155ISR.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
113
Spectra-4x155 (PM5316) Driver Manual Hardware Interface
Installing the ISR Handler: sysSpe4x155ISRHandlerInstall
This routine installs the user-supplied Interrupt-Service Routine (ISR), sysSpe4x155ISRHandler, into the processor's interrupt vector table. Format Prototype Inputs Outputs Returns Pseudocode
#define sysSpe4x155ISRHandlerInstall() INT4 sysSpe4x155ISRHandlerInstall(void)
None None Success = 0 Failure = Begin Establish communication channel (message queue) for DPR. Spawn DPR task install sysSpe4x155ISRHandler in processor's interrupt vector table End
ISR Handler: sysSpe4x155ISRHandler
This routine is invoked when one or more SPECTRA-4x155 devices raise the interrupt line to the microprocessor. This routine invokes the driver-provided routine, spe4x155ISR, for each device registered with the driver. Format Prototype Inputs Outputs Returns Pseudocode
#define sysSpe4x155ISRHandler() void sysSpe4x155ISRHandler(void)
None None None Begin for each device registered with the driver call spe4x155ISR if returned ISV buffer is not NULL send ISV buffer to the DPR End
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
114
Spectra-4x155 (PM5316) Driver Manual Hardware Interface
Removing the ISR Handler: sysSpe4x155ISRHandlerRemove
This routine disables interrupt processing for this device. Removes the user-supplied InterruptService Routine (ISR), sysSpe4x155ISRHandler, from the processor's interrupt vector table. Format Prototype Inputs Outputs Returns Pseudocode
#define sysSpe4x155ISRHandlerRemove() void sysSpe4x155ISRHandlerRemove(void)
None None None Begin remove sysSpe4x155ISRHandler from the processor's interrupt vector table destroy DPR task destroy communication channel (message queue) End
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
115
Spectra-4x155 (PM5316) Driver Manual RTOS Interface
7
RTOS INTERFACE
The SPECTRA-4x155 driver requires the use of some Real-Time Operating System (RTOS) resources. In this section, a listing of each required resource is shown, along with a declaration and any specific porting instructions. It is the responsibility of the user to connect these requirements into the RTOS, either by defining a macro or writing a function for each item listed. Care should be taken when matching parameters and return values.
7.1
Memory Allocation / De-Allocation
Allocating Memory: sysSpe4x155MemAlloc
This function allocates specified number of bytes of memory. Format Prototype Inputs Outputs Returns
#define sysSpe4x155MemAlloc(numBytes) UINT1 *sysSpe4x155MemAlloc(UINT4 numBytes) numBytes
: number of bytes to be allocated
None Success = Pointer to first byte of allocated memory Failure = NULL pointer (memory allocation failed)
Freeing Memory: sysSpe4x155MemFree
This function frees memory allocated using sysSpe4x155MemAlloc. Format Prototype Inputs
#define sysSpe4x155MemFree(pfirstByte) void sysSpe4x155MemFree(UINT1 *pfirstByte) pfirstByte
: pointer to first byte of the memory region being de-allocated
Outputs Returns
None None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
116
Spectra-4x155 (PM5316) Driver Manual RTOS Interface
Copying Memory: sysSpe4x155MemCpy
This function copies a block of memory. Format Prototype Inputs
#define sysSpe4x155MemCpy(pdst, psrc, sz) void sysSpe4x155MemCpy (UINT1 *pdst, UINT1 *psrc, UINT4 sz) pdst psrc sz pdst
: (pointer to) first byte of destination block : (pointer to) first byte of source block : block size : updated memory block
Outputs Returns
None
Setting Memory: sysSpe4x155MemSet
This function initializes a block of memory with a given value. Format Prototype Inputs
#define sysSpe4x155MemSet(pmem, val, sz) void sysSpe4x155MemSet(UINT1 *pmem, UINT1 val, UINT4 sz) pmem val sz pmem
: (pointer to) first byte of the memory region to initialize : value to use : size of the block to initialize : updated memory block
Outputs Returns
None
7.2
Buffer Management
All operating systems provide some sort of buffer system, particularly for use in sending and receiving messages. The following calls, provided by the user, allow the driver to Get and Return buffers from the RTOS. It is the user's responsibility to create any special resources or pools to handle buffers of these sizes during the sysSpe4x155BufferStart call.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
117
Spectra-4x155 (PM5316) Driver Manual RTOS Interface
Starting Buffer Management: sysSpe4x155BufferStart
This function alerts the RTOS that the time has come to make sure Interrupt-Service Vector (ISV) buffers and Deferred-Processing Vector (DPV) buffers are available and sized correctly. This may involve the creation of new buffer pools and it may involve nothing, depending on the RTOS. Format Prototype Inputs Outputs Returns
#define sysSpe4x155BufferStart() INT4 sysSpe4x155BufferStart(void)
None None Success = 0 Failure =
Getting an ISV Buffer: sysSpe4x155ISVBufferGet
This function gets a buffer from the RTOS that will be used by the Interrupt-Service Routine (ISR) code to create an Interrupt-Service Vector (ISV). The ISV consists of data transferred from the devices interrupt status registers. Format Prototype Inputs Outputs Returns
#define sysSpe4x155ISVBufferGet() sSPE4X155_ISV *sysSpe4x155ISVBufferGet(void)
None None Success = (pointer to) a ISV buffer Failure = NULL (pointer)
Returning an ISV Buffer: sysSpe4x155ISVBufferRtn
This function returns an ISV buffer to the RTOS when the information in the block is no longer needed by the DPR. Format Prototype Inputs Outputs
#define sysSpe4x155ISVBufferRtn(pISV) void sysSpe4x155ISVBufferRtn(sSPE4X155_ISV *pisv) pisv
: (pointer to) a ISV buffer
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
118
Spectra-4x155 (PM5316) Driver Manual RTOS Interface
Returns
None
Getting a DPV Buffer: sysSpe4x155DPVBufferGet
This function gets a buffer from the RTOS that will be used by the Deferred-Processing Routine (DPR) code to create a Deferred-Processing Vector (DPV). The DPV consists of information about the state of the device that is to be passed to the user via a callback function. Format Prototype Inputs Outputs Returns
#define sysSpe4x155DPVBufferGet() sSPE4X155_DPV *sysSpe4x155DPVBufferGet(void)
None None Success = (pointer to) a DPV buffer Failure = NULL (pointer)
Returning a DPV Buffer: sysSpe4x155DPVBufferRtn
This function returns a DPV buffer to the RTOS when the information in the block is no longer needed by the DPR. Format Prototype Inputs Outputs Returns
#define sysSpe4x155DPVBufferRtn(pDPV) void sysSpe4x155DPVBufferRtn(sSPE4X155_DPV *pdpv) pdpv
: (pointer to) a DPV buffer
None None
Stopping Buffer Management: sysSpe4x155BufferStop
This function alerts the RTOS that the driver no longer needs any of the ISV buffers or DPV buffers and that if any special resources were created to handle these buffers, they can be deleted now. Format Prototype Inputs
#define sysSpe4x155BufferStop() void sysSpe4x155BufferStop(void)
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
119
Spectra-4x155 (PM5316) Driver Manual RTOS Interface
Outputs Returns
None None
7.3
Timers
Sleeping a Task: sysSpe4x155TimerSleep
This function suspends execution of a driver task for a specified number of milliseconds. Format Prototype Inputs Outputs Returns
#define sysSpe4x155TimerSleep(time) void sysSpe4x155TimerSleep(UINT4 time) time
: sleep time in milliseconds
None Success = 0 Failure =
7.4
Preemption
Disabling Preemption: sysSpe4x155PreemptDisable
This function prevents the calling task from being preempted. If the driver is in interrupt mode, this routine locks out all interrupts as well as other tasks in the system. If the driver is in polling mode, this routine locks out other tasks only. Format Prototype Inputs Outputs Returns
#define sysSpe4x155PreemptDisable() INT4 sysSpe4x155PreemptDisable(void)
None None Preemption key (passed back as an argument in
sysSpe4x155PreemptEnable)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
120
Spectra-4x155 (PM5316) Driver Manual RTOS Interface
Re-Enabling Preemption: sysSpe4x155PreemptEnable
This function allows the calling task to be preempted. If the driver is in interrupt mode, this routine unlocks all interrupts and other tasks in the system. If the driver is in polling mode, this routine unlocks other tasks only. Format Prototype Inputs
#define sysSpe4x155PreemptEnable(key) void sysSpe4x155PreemptEnable(INT4 key) key
: preemption key (returned by
sysSpe4x155PreemptDisable)
Outputs Returns
None None
7.5
System-Specific DPR Routine
The porting of a task between platforms is not always simple. There are many different implementations of the RTOS level parameters. In this driver, the user is responsible for creating a `shell' (sysSpe4x155DPRTask) that in turn calls spe4x155DPR with an ISV to perform the ISR related processing that is required by each interrupting device. During execution of the API function spe4x155ModuleStart / spe4x155ModuleStop the driver informs the application that it is time to install / uninstall this shell that needs to be supplied by the user.
DPR Task: sysSpe4x155DPRTask
This routine is installed as a separate task within the RTOS. It runs periodically and retrieves the interrupt status information sent to it by spe4x155ISR and then invokes spe4x155DPR for the appropriate device. Format Prototype Inputs Outputs Returns
#define sysSpe4x155DPRTask() void sysSpe4x155DPRTask(void)
None None None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
121
Spectra-4x155 (PM5316) Driver Manual RTOS Interface
Pseudocode
Begin do wait for an ISV buffer (sent by spe4x155ISR) call spe4x155DPR with that ISV loop forever End
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
122
Spectra-4x155 (PM5316) Driver Manual Porting the SPECTRA-4x155 Driver
8
PORTING THE SPECTRA-4X155 DRIVER
This section outlines how to port the SPECTRA-4x155 device driver to your hardware and OS platform. However, this manual can offer only guidelines for porting the SPECTRA-4x155 driver because each platform and application is unique.
8.1
Driver Source Files
The C files listed in the following table contain the code for the SPECTRA-4x155 driver. You may need to modify the code or develop additional code. The code is in the form of constants, macros, and functions. For the ease of porting, the code is grouped into source files (src) and header files (inc). The source files contain the functions and the header files contain the structures, constants and macros. Directory
src
File
spe4x155_api1.c
Description All the API functions that take care of module, device and profile management All the SPECTRA-4x155 specific API functions Hardware interface functions Internal functions for interrupt servicing Internal functions for profiles RTOS interface functions Internal functions for statistics All the remaining internal functions All API headers Driver macros, constants and definitions (such as register mapping and bit masks) SPECTRA-4x155 error codes Prototype of non-API functions HW interface macros and prototype RTOS interface macros and prototypes
spe4x155_api2.c spe4x155_hw.c spe4x155_isr.c spe4x155_prof.c spe4x155_rtos.c spe4x155_stat.c spe4x155_util.c inc spe4x155_api.h spe4x155_defs.h
spe4x155_err.h spe4x155_fns.h spe4x155_hw.h spe4x155_rtos.h
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
123
Spectra-4x155 (PM5316) Driver Manual Porting the SPECTRA-4x155 Driver
Directory
inc
File
spe4x155_strs.h spe4x155_typs.h
Description Driver structures Types definitions Sample driver callback functions and example code Prototypes, macros and structures used inside the example code Example debug task Example debug task defines and prototypes
example
spe4x155_app.c
spe4x155_app.h
spe4x155_debug.c spe4x155_debug.h
8.2
Driver Porting Procedures
The following procedures summarize how to port the SPECTRA-4x155 driver to your platform. The subsequent sections describe these procedures in more detail. To port the SPECTRA-4x155 driver to your platform: Step 1: Port the driver's RTOS interface (page 124). Step 2: Port the driver's hardware interface (page 126). Step 3: Port the driver's application-specific elements (page 127). Step 4: Build the driver.
Step 1: Porting the RTOS interface
The Real-Time Operating System (RTOS) interface functions and macros consist of code that is RTOS dependent and needs to be modified as per your RTOS's characteristics. To port the driver's OS extensions: 1. Redefine the following macros and functions in the spe4x155_rtos.h file to the corresponding system calls that your target system supports:
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
124
Spectra-4x155 (PM5316) Driver Manual Porting the SPECTRA-4x155 Driver
Service Type Memory
Macro Name
sysSpe4x155MemAlloc sysSpe4x155MemFree sysSpe4x155MemCpy
Description Allocates a memory block Frees a memory block Copies the contents of one memory block to another Fills a memory block with a specified value Delays the task execution for a given number of milliseconds Disables pre-emption of the currently executing task by any other task or interrupt Re-enables pre-emption of a task by other tasks and/or interrupts
sysSpe4x155MemSet
Timer
sysSpe4x155TimerSleep
Pre-emption Lock/Unlock
sysSpe4x155PreemptDisable
sysSpe4x155PreemptEnable
2. Modify the example implementation of the buffer management routines provided in the spe4x155_rtos.h file with the corresponding system calls that your target system supports: Service Type Buffer Macro Name
sysSpe4x155BufferStart sysSpe4x155BufferStop sysSpe4x155ISVBufferGet
Description Starts buffer management Stops buffer management Gets an ISV buffer from the ISV buffer queue Returns an ISV buffer to the ISV buffer queue Gets a DPV buffer from the DPV buffer queue Returns a DPV buffer to the DPV buffer queue
sysSpe4x155ISVBufferRtn
sysSpe4x155DPVBufferGet
sysSpe4x155DPVBufferRtn
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
125
Spectra-4x155 (PM5316) Driver Manual Porting the SPECTRA-4x155 Driver
3. Define the following constants for your OS-specific services in spe4x155_rtos.h: Task Constant
SPE4X155_DPR_TASK_PRIORITY SPE4X155_DPR_TASK_STACK_SZ
Description Deferred Task (DPR) task priority DPR task stack size, in bytes
Default 85 8192
Step 2: Porting the Hardware Interface
This section describes how to modify the SPECTRA-4x155 driver for your hardware platform. To port the driver to your hardware platform: 1. Modify the variable type definitions in spe4x155_typs.h. 2. Modify the low-level hardware-dependent functions and macros in the spe4x155_hw.h file. You may need to modify the raw read/write access macros (sysSpe4x155Read and sysSpe4x155Write) to reflect your system's addressing logic. Service Type Function Name Description Reads a device register given its real address in memory Writes to a device register given its real address in memory Installs the interrupt handler for the OS, spawns the DPR task, and creates the DPR message queue Removes the interrupt handler from the OS, destroys the DPR task and frees the DPR message queue Interrupt handler for the SPECTRA-4x155 device Task that calls the SPECTRA-4x155 DPR
Register Access sysSpe4x155Read
sysSpe4x155Write
Interrupt
sysSpe4x155ISRHandlerInstall
sysSpe4x155ISRHandlerRemove
sysSpe4x155ISRHandler
sysSpe4x155DPRTask
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
126
Spectra-4x155 (PM5316) Driver Manual Porting the SPECTRA-4x155 Driver
3. Define the hardware system-configuration constants in the spe4x155_hw.h file. Modify the following constants to reflect your system's hardware configuration: Device Constant
SPE4X155_MAX_DELAY
Description Delay between two consecutive polls of a busy bit Maximum number of times a busy bit will be polled before the operation times out
Default 100us
SPE4X155_MAX_POLL
100
Step 3: Porting the Application-Specific Elements
Porting the application-specific elements includes coding the application callback and defining all the constants used by the API. To port the driver's application-specific elements: 1. Modify the base value of SPE4X155_ERR_BASE (default = -600) in spe4x155_err.h. 2. Define the following application specific constants in spe4x155_defs.h: Task Constant
SPE4X155_MAX_DEVS
Description The maximum number of SPECTRA4x155 devices that can be supported by the driver The maximum number of initialization profiles that can be added to the driver
Default 16
SPE4X155_MAX_INIT_PROFS
20
3. Define the following constants for your OS-specific services in spe4x155_rtos.h
SPE4X155_MAX_ISV_BUF
The queue message depth of the queue used for passing interrupt context between the ISR handler and the DPR task The queue message depth of the queue used for pass interrupt context between the DPR task and the callback functions
50
SPE4X155_MAX_DPV_BUF
950
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
127
Spectra-4x155 (PM5316) Driver Manual Porting the SPECTRA-4x155 Driver
4. Code the callback functions according to your application. Example implementations of these callbacks are provided in app.c. The driver will call these callback functions when an event occurs on the device. These functions must conform to the following prototype: void cbackXX (sSPE4X155_USR_CTXT usrCtxt, void *pdpv)
Step 4: Building the Driver
This section describes how to build the SPECTRA-4x155 driver. To build the driver: 1. Modify the Makefile to reflect the absolute path of your code, your compiler and compiler options. 2. Choose from among the different compile options supported by the driver as per your requirements. 3. Compile the source files and build the SPECTRA-4x155 API driver library using your make utility. 4. Link the SPECTRA-4x155 API driver library to your application code.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
128
Spectra-4x155 (PM5316) Driver Manual Appendix A: Coding Conventions
APPENDIX A: CODING CONVENTIONS
This appendix describes the coding conventions used in the implementation of all PMC driver software.
Variable Type Definitions
Table 25: Variable Type Definitions Type
UINT1 UINT2 UINT4 INT1 INT2 INT4
Description unsigned integer - 1 byte unsigned integer - 2 bytes unsigned integer - 4 bytes signed integer - 1 byte signed integer - 2 bytes signed integer - 4 bytes
Naming Conventions
Table 26 presents a summary of the naming conventions followed by all PMC driver software. A detailed description is then given in the following sub-sections. The names used in the drivers are verbose enough to make their purpose fairly clear. This makes the code more readable. Generally, the device's name or abbreviation appears in prefix. Table 26: Naming Conventions Type Macros Case Uppercase Naming convention prefix with "m" and device abbreviation prefix with device abbreviation Examples
mSPE4X155_SLICE_OFFSET
Constants
Uppercase
SPE4X155_MAX_DEVS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
129
Spectra-4x155 (PM5316) Driver Manual Appendix A: Coding Conventions
Type Structures
Case Hungarian Notation Hungarian Notation Hungarian Notation Hungarian Notation Hungarian Notation
Naming convention prefix with "s" and device abbreviation prefix with device name
Examples
sSPE4X155_DDB
API Functions Porting Functions Other Functions Variables
spe4x155Add()
prefix with "sys" and device name --
sysSpe4x155Read()
utilSpe4x155ApplyDIV()
--
maxDevs
Pointers to Hungarian variables Notation Global variables Hungarian Notation
prefix variable name with
"p"
pmaxDevs
prefix with device name
spe4x155Mdb
Macros
* * * * Macro names must be all uppercase. Words shall be separated by an underscore. The letter `m' in lowercase is used as a prefix to specify that it is a macro, then the device abbreviation must appear. Example: mSPE4X155_SLICE_OFFSET is a valid name for a macro.
Constants
* * * * Constant names must be all uppercase. Words shall be separated by an underscore. The device abbreviation must appear as a prefix. Example: SPE4X155_MAX_DEVS is a valid name for a constant.
Structures
* * Structure names must be all uppercase. Words shall be separated by an underscore.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
130
Spectra-4x155 (PM5316) Driver Manual Appendix A: Coding Conventions
* *
The letter `s' in lowercase must be used as a prefix to specify that it is a structure, then the device abbreviation must appear. Example: sSPE4X155_DDB is a valid name for a structure.
Functions
API Functions * * * Naming of the API functions must follow the hungarian notation. The device's full name in all lowercase shall be used as a prefix. Example: spe4x155Add() is a valid name for an API function.
Porting Functions Porting functions correspond to all function that are HW and/or RTOS dependent. * * * * Naming of the porting functions must follow the hungarian notation. The `sys' prefix shall be used to indicate a porting function. The device's name starting with an uppercase must follow the prefix. Example: sysSpe4x155Read() is a hardware / RTOS specific.
Other Functions * * Other Functions are all the remaining functions that are part of the driver and have no special naming convention. However, they must follow the hungarian notation. Example: utilSpe4x155ApplyDIV is a valid name for such a function.
Variables
* * Naming of variables must follow the hungarian notation. A pointer to a variable shall use `p' as a prefix followed by the variable name unchanged. If the variable name already starts with a `p', the first letter of the variable name may be capitalized, but this is not a requirement. Double pointers might be prefixed with `pp', but this is not required. Global variables must be identified with the device's name in all lowercase as a prefix. Examples: maxDevs is a valid name for a variable, pmaxDevs is a valid name for a pointer to maxDevs, and is a valid name for a global variable. Note that both pprevBuf and pPrevBuf are accepted names for a pointer to the prevBuf variable, and that both pmatrix and ppmatrix are accepted names for a double pointer to the variable matrix.
* *
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
131
Spectra-4x155 (PM5316) Driver Manual Appendix A: Coding Conventions
File Organization
Table 27 presents a summary of the file naming conventions. All file names must start with the device abbreviation, followed by an underscore and the actual file name. File names should convey their purpose with a minimum amount of characters. If a file size is getting too big one might separate it into two or more files, providing that a number is added at the end of the file name (e.g. spe4x155_api1.c or spe4x155_api2.c). There are 4 different types of files: * * * * The API file containing all the API functions The hardware file containing the hardware dependent functions The RTOS file containing the RTOS dependent functions The other files containing all the remaining functions of the driver
Table 27: File Naming Conventions File Type API Hardware Dependent RTOS Dependent Other File Name
spe4x155_api1.c, spe4x155_api.h spe4x155_hw.c, spe4x155_hw.h spe4x155_rtos.c, spe4x155_rtos.h spe4x155_stat.c, spe4x155_util.c
API Files
* * The name of the API files must start with the device abbreviation followed by an underscore and `api'. Eventually a number might be added at the end of the name. Examples: spe4x155_api1.c is the only valid name for the file that contains the first part of the API functions, spe4x155_api.h is the only valid name for the file that contains all of the API functions headers.
Hardware Dependent Files
* * The name of the hardware dependent files must start with the device abbreviation followed by an underscore and `hw'. Eventually a number might be added at the end of the file name. Examples: spe4x155_hw.c is the only valid name for the file that contains all of the hardware dependent functions, spe4x155_hw.h is the only valid name for the file that contains all of the hardware dependent functions headers.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
132
Spectra-4x155 (PM5316) Driver Manual Appendix A: Coding Conventions
* * *
RTOS Dependent Files The name of the RTOS dependent files must start with the device abbreviation followed by an underscore and `rtos'. Eventually a number might be added at the end of the file name. Examples: spe4x155_rtos.c is the only valid name for the file that contains all of the RTOS dependent functions, spe4x155_rtos.h is the only valid name for the file that contains all of the RTOS dependent functions headers.
Other Driver Files
* The name of the remaining driver files must start with the device abbreviation followed by an underscore and the file name itself, which should convey the purpose of the functions within that file with a minimum amount of characters. Examples: spe4x155_isr.c is a valid name for a file that would deal with interrupt servicing for the device.
*
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
133
Spectra-4x155 (PM5316) Driver Manual Appendix B: Driver Return Codes
APPENDIX B: DRIVER RETURN CODES
This appendix describes the error codes used in the SPECTRA-4X155 device driver. Table 28: Return Codes Return Type
SPE4X155_ERR_MEM_ALLOC SPE4X155_ERR_INVALID_ARG SPE4X155_ERR_INVALID_MODULE_STATE SPE4X155_ERR_INVALID_MIV SPE4X155_ERR_PROFILES_FULL
Description Memory allocation failure Invalid argument Invalid module state Invalid Module Initialization Vector Maximum number of profiles already added Invalid profile Invalid profile number Invalid device state Maximum number of devices already added Device already added Invalid device handle Invalid Device Initialization Vector Error while installing interrupts Invalid ISR/polling mode Invalid register number Time-out while polling
SPE4X155_ERR_INVALID_PROFILE SPE4X155_ERR_INVALID_PROFILE_NUM SPE4X155_ERR_INVALID_DEVICE_STATE SPE4X155_ERR_DEVS_FULL
SPE4X155_ERR_DEV_ALREADY_ADDED SPE4X155_ERR_INVALID_DEV SPE4X155_ERR_INVALID_DIV SPE4X155_ERR_INT_INSTALL SPE4X155_ERR_INVALID_MODE SPE4X155_ERR_INVALID_REG SPE4X155_ERR_POLL_TIMEOUT
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
134
Spectra-4x155 (PM5316) Driver Manual Appendix C: Events
APPENDIX C: EVENTS
This appendix describes the events used in the SPECTRA-4x155 device driver. Table 29: SPECTRA-4x155 Events for IO callbacks Event
SPE4X155_EVENT_IO_TROOL SPE4X155_EVENT_IO_RROOL SPE4X155_EVENT_IO_RDOOL SPE4X155_EVENT_IO_APARRERR SPE4X155_EVENT_IO_RDOOL_AUX
Description Transmit reference clock out of lock Receive reference clock out of lock Receive data out of lock ADD bus parity error Receive data out of lock state change
Table 30: SPECTRA-4x155 Events for SOH callbacks Event
SPE4X155_EVENT_SOH_BIPE SPE4X155_EVENT_SOH_LOS SPE4X155_EVENT_SOH_LOF SPE4X155_EVENT_SOH_OOF SPE4X155_EVENT_SOH_TIU SPE4X155_EVENT_SOH_TIM SPE4X155_EVENT_SOH_OOF_AUX SPE4X155_EVENT_SOH_LOS_AUX SPE4X155_EVENT_SOH_LOF_AUX
Description Section BIP error Loss of signal Loss of frame Out of frame Section trace identifier unstable Section trace identifier mismatch Out of frame state change Loss of signal state change Loss of frame state change
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
135
Spectra-4x155 (PM5316) Driver Manual Appendix C: Events
Table 31: SPECTRA-4x155 Events for LOH callbacks Event
SPE4X155_EVENT_LOH_BIPE SPE4X155_EVENT_LOH_REI SPE4X155_EVENT_LOH_SF SPE4X155_EVENT_LOH_SD SPE4X155_EVENT_LOH_COSSM SPE4X155_EVENT_LOH_COAPS SPE4X155_EVENT_LOH_APSBF SPE4X155_EVENT_LOH_RDI SPE4X155_EVENT_LOH_AIS SPE4X155_EVENT_LOH_RDI_AUX SPE4X155_EVENT_LOH_AIS_AUX SPE4X155_EVENT_LOH_SF_AUX SPE4X155_EVENT_LOH_SD_AUX
Description Line BIP error Line remote error indication error Signal failure Signal degrade Change of SSM message (Z1/S1) Change of APS bytes (K1, K2) APS byte failure Line alarm indication signal Line remote defect indication Line RDI state change Line AIS state change Signal fail. Signal degrade.
Table 32: SPECTRA-4x155 Events for RPOH callback Event
SPE4X155_EVENT_RPOH_RDI_AUX SPE4X155_EVENT_RPOH_AIS_AUX SPE4X155_EVENT_RPOH_PSLU_AUX SPE4X155_EVENT_RPOH_PSLM_AUX SPE4X155_EVENT_RPOH_LOP_AUX SPE4X155_EVENT_RPOH_LOM_AUX SPE4X155_EVENT_RPOH_TIU_AUX
Description Path RDI state change Path AIS state change Path signal label unstable state change Path signal label mismatch state change Loss of pointer state change Loss of multiframe state change Trace identifier unstable mode 1 state change
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
136
Spectra-4x155 (PM5316) Driver Manual Appendix C: Events
Event
SPE4X155_EVENT_RPOH_TIM_AUX SPE4X155_EVENT_RPOH_LOPC_AUX SPE4X155_EVENT_RPOH_AISC_AUX SPE4X155_EVENT_RPOH_ERDI_AUX
Description Trace identifier mismatch state change Loss of pointer concatenation state change Path AIS concatenation state change Path enhanced remote defect indication state change Reception of new pointer indication Path loss of pointer concatenated Path Loss of pointer Path AIS concatenated Path AIS Path remote defect indication Path BIP error Path remote error indication Change of path enhanced remote defect indication Illegal pointer justification request Concatenation indicator error in STS-1/STM0/AU-3 Change of pointer alignment event Invalid NDF code Positive pointer justification indication received Negative pointer justification indication received Detection of NDF_enable indication. Loss of multiframe
SPE4X155_EVENT_RPOH_NEWPTR SPE4X155_EVENT_RPOH_LOPC SPE4X155_EVENT_RPOH_LOP SPE4X155_EVENT_RPOH_AISC SPE4X155_EVENT_RPOH_AIS SPE4X155_EVENT_RPOH_PRDI SPE4X155_EVENT_RPOH_BIPE SPE4X155_EVENT_RPOH_PREI SPE4X155_EVENT_RPOH_PERDI
SPE4X155_EVENT_RPOH_ILLJREQ SPE4X155_EVENT_RPOH_CONCAT
SPE4X155_EVENT_RPOH_DISCOPA SPE4X155_EVENT_RPOH_INVNDF SPE4X155_EVENT_RPOH_PSE
SPE4X155_EVENT_RPOH_NSE
SPE4X155_EVENT_RPOH_NDF SPE4X155_EVENT_RPOH_LOM
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
137
Spectra-4x155 (PM5316) Driver Manual Appendix C: Events
Event
SPE4X155_EVENT_RPOH_COMA SPE4X155_EVENT_RPOH_ESE SPE4X155_EVENT_RPOH_PPJ
Description Change of multiframe alignment Elastic store error DROP bus positive pointer justification inserted. DROP bus negative pointer justification inserted. Path connection unequipped Path trace identifier unstable Path trace identifier mismatch Path signal label mismatch Path signal label unstable Illegal Pointer Change of Path Signal Label
SPE4X155_EVENT_RPOH_NPJ
SPE4X155_EVENT_RPOH_UNEQ SPE4X155_EVENT_RPOH_TIU SPE4X155_EVENT_RPOH_TIM SPE4X155_EVENT_RPOH_PSLM SPE4X155_EVENT_RPOH_PSLU SPE4X155_EVENT_RPOH_ILLPTR SPE4X155_EVENT_RPOH_COPSL
Table 33: SPECTRA-4x155 Events for TPOH callback Event
SPE4X155_EVENT_TPOH_LOPC_AUX
Description Change in transmit loss of pointer concatenation state Change in transmit path AIS concatenation state Change in transmit path AIS state. Change in transmit loss of pointer state Change in transmit loss of multiframe state Elastic store FIFO overflow/underflow error Transmit stream positive pointer justification Transmit stream negative pointer justification
SPE4X155_EVENT_TPOH_AISC_AUX
SPE4X155_EVENT_TPOH_AIS_AUX SPE4X155_EVENT_TPOH_LOP_AUX SPE4X155_EVENT_TPOH_LOM_AUX SPE4X155_EVENT_TPOH_ESE SPE4X155_EVENT_TPOH_PPJ SPE4X155_EVENT_TPOH_NPJ
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
138
Spectra-4x155 (PM5316) Driver Manual Appendix C: Events
Event
SPE4X155_EVENT_TPOH_NEWPTR SPE4X155_EVENT_TPOH_LOPC
Description New point indication received Change in transmit AU-3 loss of pointer concatenation status Change in transmit loss of pointer status Change in transmit path AIS concatenation status Change in transmit path AIS status Change in transmit path remote defect indication Change in transmit path BIP error status Change in transmit path extended remote error indication status Illegal justification request event Discontinuous pointer change Invalid NDF observed in receive stream Illegal pointer observed in receive stream Responded to a dec_ind indication in the receive stream Responded to an inc_ind indication in receive stream NDF enable patter observed in receive stream Change in loss of multiframe status in received stream Change in multiframe alignment Error detected in concatenation indicators of STS-1
SPE4X155_EVENT_TPOH_LOP SPE4X155_EVENT_TPOH_AISC
SPE4X155_EVENT_TPOH_AIS SPE4X155_EVENT_TPOH_RDI
SPE4X155_EVENT_TPOH_BIPE SPE4X155_EVENT_TPOH_REI
SPE4X155_EVENT_TPOH_ILLJREQ SPE4X155_EVENT_TPOH_DISCOPA SPE4X155_EVENT_TPOH_INVNDF SPE4X155_EVENT_TPOH_ILLPTR SPE4X155_EVENT_TPOH_NSE
SPE4X155_EVENT_TPOH_PSE
SPE4X155_EVENT_TPOH_NDF SPE4X155_EVENT_TPOH_LOM
SPE4X155_EVENT_TPOH_COMA SPE4X155_EVENT_TPOH_CONCAT
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
139
Spectra-4x155 (PM5316) Driver Manual Appendix C: Events
Table 34: SPECTRA-4x155 Events for DPGM callback Event
SPE4X155_EVENT_DPGM_GENSIG SPE4X155_EVENT_DPGM_MONERR
Description DROP generator signal DROP monitor error detected in received PRBS byte DROP monitor synchronization state change DROP monitor signal verification state by a slave monitor
SPE4X155_EVENT_DPGM_MONSYNC SPE4X155_EVENT_DPGM_MONSIG
Table 35: SPECTRA-4x155 Events for APGM callback Event
SPE4X155_EVENT_APGM_GENSIG SPE4X155_EVENT_APGM_MONERR
Description ADD generator signal ADD monitor error detected in received PRBS byte ADD monitor synchronization state change ADD monitor signal verification state by a slave monitor
SPE4X155_EVENT_APGM_MONSYNC SPE4X155_EVENT_APGM_MONSIG
The cause value passed to the callback contains the following values, where Aux refers to any event ending in _AUX with a mask bit ending in Aux, and Non-Aux refers to all other events. Table 36: SPECTRA-4x155 Event Cause Values Event Type IO (except TROOL) SOH LOH RPOH TPOH Cause value STM-1 # STM-1 # STM-1 # Non-Aux: 0x01XY Aux: 0x02XY where X=AU-3 # and Y=STM-1 # Non-Aux: 0x01XY Aux: 0x02XY where X=AU-3 # and Y=STM-1 #
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
140
Spectra-4x155 (PM5316) Driver Manual Appendix C: Events
DPGM APGM
0x00XY where X=AU-3 # and Y=STM-1 # 0x00XY where X=AU-3 # and Y=STM-1 #
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
141
Spectra-4x155 (PM5316) Driver Manual
LIST OF TERMS
APPLICATION: Refers to protocol software used in a real system as well as validation software written to validate the SPECTRA-4x155 driver on a validation platform. API (Application Programming Interface): Describes the connection between this module and the user's application code. ISR (Interrupt-Service Routine): A common function for intercepting and servicing device events. This function is kept as short as possible because an interrupt preempts every other function starting the moment it occurs and gives the service function the highest priority while running. Data is collected, interrupt indicators are cleared and the function ended. DPR (Deferred-Processing Routine): This function is installed as a task, at a user configurable priority, that serves as the next logical step in interrupt processing. Data that was collected by the ISR is analyzed and then calls are made into the application that inform it of the events that caused the ISR in the first place. Because this function is operating at the task level, the user can decide on its importance in the system, relative to other functions. DEVICE: One SPECTRA-4x155 Integrated Circuit. There can be many devices, all served by this one driver module * DIV (Device Initialization Vector): Structure passed from the API to the device during initialization; it contains parameters that identify the specific modes and arrangements of the physical device being initialized. DDB (Device Data Block): Structure that holds the Configuration Data for each device.
*
MODULE: All of the code that is part of this driver, there is only one instance of this module connected to one or more SPECTRA-4x155 chips. * MIV (Module Initialization Vector): Structure passed from the API to the module during initialization, it contains parameters that identify the specific characteristics of the driver module being initialized. MDB (Module Data Block): Structure that holds the Configuration Data for this module.
*
RTOS (Real-Time Operating System): The host for this driver
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
142
Spectra-4x155 (PM5316) Driver Manual
ACRONYMS
APGM: Add Bus PRBS Generator and Monitor API: Application Programming Interface DDB: Device Data Block DIV: Device Initialization Vector DPGM: Drop Bus PRBS Generator and Monitor DPR: Deferred-Processing Routine DPV: Deferred-Processing (routine) Vector FIFO: First In, First Out IO: Input / Output ISR: Interrupt-Service Routine ISV: Interrupt-Service (routine) Vector LOH: Line Overhead LOP: Loss of Pointer MDB: Module Data Block MIV: Module Initialization Vector POH: Path Overhead PRSB: Pseudo Random Bit Sequence RPOH: Receive Path Overhead RTOS: Real-Time Operating System SOH: Section Overhead TPOH: Transmit Path Overhead TSI: Time-Slot Interchange
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
143
Spectra-4x155 (PM5316) Driver Manual
INDEX
A
api functions
spe4x155Activate - 63 spe4x155Add - 50, 60, 61, 149, 150 spe4x155APGMGenCfg - 102 spe4x155APGMGenForceErr - 104 spe4x155APGMGenRegen - 103 spe4x155APGMMonCfg - 102, 103 spe4x155APGMMonResync - 104 spe4x155CfgStats - 34, 111 spe4x155ClearMask - 35, 107 spe4x155ClrInitProfile - 59 spe4x155DeActivate - 63 spe4x155Delete - 28, 56, 57, 60 spe4x155DiagLineLoop - 120 spe4x155DiagParaLoop - 121 spe4x155DiagSerialLoop - 121 spe4x155DiagSysSideLineLoop - 122 spe4x155DiagTestReg - 120 spe4x155DPGMGenCfg - 99 spe4x155DPGMGenForceErr - 101 spe4x155DPGMGenRegen - 100, 126 spe4x155DPGMMonCfg - 99 spe4x155DPGMMonResync - 101 spe4x155DPR - 21, 27, 28, 29, 109, 123, 138 spe4x155GetCnt - 40, 112 spe4x155GetCntLOH - 40, 113 spe4x155GetCntPJ - 115 spe4x155GetCntPOH - 40 spe4x155GetCntRPOH - 114 spe4x155GetCntSOH - 40, 112, 113 spe4x155GetCntTPOH - 114, 115 spe4x155GetInitProfile - 58 spe4x155GetMask - 35, 106 spe4x155GetStatus - 116 spe4x155GetStatusIO - 116 spe4x155GetStatusLOH - 118 spe4x155GetStatusRPOH - 118 spe4x155GetStatusSOH - 117 spe4x155GetStatusTPOH - 119 spe4x155GetThresh - 110 spe4x155GetThreshCntr - 111 spe4x155Init - 31, 61, 62, 108, 123, 124, 125, 126, 127 spe4x155IOGetDestSlot - 70 spe4x155IOGetSrcSlot - 71 spe4x155IOIsMulticast - 69 spe4x155IOMapSlot - 68 spe4x155ISR - 21, 27, 28, 29, 108, 129, 130, 131, 138 spe4x155ISRConfig - 105, 108 spe4x155LOHCfgSFSD - 82 spe4x155LOHDiagB2 - 80, 81 spe4x155LOHInsertLineAIS - 81 spe4x155LOHInsertLineRDI - 80 spe4x155LOHReadK1K2 - 77, 78 spe4x155LOHReadS1 - 79 spe4x155LOHTermination - 77 spe4x155LOHWriteK1K2 - 78 spe4x155LOHWriteS1 - 79 spe4x155ModuleClose - 56 spe4x155ModuleOpen - 31, 55 spe4x155ModuleStart - 56, 129, 138 spe4x155ModuleStop - 57, 129, 138 spe4x155PathTraceMsg - 83 spe4x155Poll - 29, 31, 105, 108, 130 spe4x155Read - 64 spe4x155ReadBlock - 65 spe4x155Reset - 62 spe4x155RINGLineAISControl - 67 spe4x155RINGLineRDIControl - 68 spe4x155RPOHDiagH4 - 87 spe4x155RPOHDiagLOP - 85 spe4x155RPOHDiagPJ - 86 spe4x155RPOHInsertPAIS - 88 spe4x155RPOHInsertTUAIS - 87 spe4x155RPOHPathSignalLabel - 85
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
144
Spectra-4x155 (PM5316) Driver Manual
spe4x155RPOHTermination - 84 spe4x155SectionTraceMsg - 72 spe4x155SetInitProfile - 31, 57, 58 spe4x155SetMask - 35, 106, 107 spe4x155SetThresh - 109 spe4x155SetThreshCntr - 111 spe4x155SOHDiagB1 - 75 spe4x155SOHDiagFB - 74 spe4x155SOHDiagLOS - 76 spe4x155SOHDiagOOF - 74 spe4x155SOHTermination - 72 spe4x155SOHWriteZ0 - 73 spe4x155TPOHDiagB3 - 90 spe4x155TPOHDiagH4 - 97 spe4x155TPOHDiagPJ - 96 spe4x155TPOHForceTxPtr - 90 spe4x155TPOHInsertNDF - 91 spe4x155TPOHInsertPAIS - 98 spe4x155TPOHInsertPREI - 93 spe4x155TPOHInsertTUAIS - 97 spe4x155TPOHTermination - 89 spe4x155TPOHWriteC2 - 92 spe4x155TPOHWriteF2 - 93 spe4x155TPOHWriteJ1 - 92 spe4x155TPOHWriteZ3 - 94 spe4x155TPOHWriteZ4 - 95 spe4x155TPOHWriteZ5 - 95 spe4x155Update - 62 spe4x155Write - 65 spe4x155WriteBlock - 66
constants
DPR SPE4X155_DPR_EVENT - 54 SPE4X155_DPR_TASK_PRIORITY - 144 SPE4X155_DPR_TASK_STACK_SZ - 144 error SPE4X155_ERR_BASE - 146 SPE4X155_ERR_DEV_ALREADY_ADDED - 60, 153 SPE4X155_ERR_DEVS_FULL - 60, 153 SPE4X155_ERR_INT_INSTALL - 154 SPE4X155_ERR_INVALID_ARG - 153 SPE4X155_ERR_INVALID_DEV - 153, 154 SPE4X155_ERR_INVALID_DEVICE_STATE - 153 SPE4X155_ERR_INVALID_DIV - 61, 62, 154 SPE4X155_ERR_INVALID_MIV - 55, 153 SPE4X155_ERR_INVALID_MODE - 106, 108, 154 SPE4X155_ERR_INVALID_MODULE_STATE - 55, 56, 57, 58, 59, 60, 153 SPE4X155_ERR_INVALID_PROFILE - 58, 59, 61, 62, 153 SPE4X155_ERR_INVALID_PROFILE_NUM - 58, 59, 61, 62, 153 SPE4X155_ERR_INVALID_REG - 64, 65, 66, 67, 154 SPE4X155_ERR_MEM_ALLOC - 55, 153 SPE4X155_ERR_POLL_TIMEOUT - 73, 83, 154 SPE4X155_ERR_PROFILES_FULL - 58, 153 SPE4X155_FAILURE - 49, 50, 54 event SPE4X155_EVENT_APGM_GENSIG - 165 SPE4X155_EVENT_APGM_MONERR - 165 SPE4X155_EVENT_APGM_MONSIG - 165 SPE4X155_EVENT_APGM_MONSYNC - 165 SPE4X155_EVENT_DPGM_GENSIG - 165 SPE4X155_EVENT_DPGM_MONERR - 165 SPE4X155_EVENT_DPGM_MONSIG - 165 SPE4X155_EVENT_DPGM_MONSYNC - 165 SPE4X155_EVENT_IO_APARRERR - 155 SPE4X155_EVENT_IO_RDOOL - 155 SPE4X155_EVENT_IO_RDOOL_AUX - 155 SPE4X155_EVENT_IO_RROOL - 155 SPE4X155_EVENT_IO_TROOL - 155 SPE4X155_EVENT_LOH_AIS - 157
C
callbacks
cbackSpe4x155APGM - 127 cbackSpe4x155DPGM - 126 cbackSpe4x155IO - 123 cbackSpe4x155LOH - 124 cbackSpe4x155RPOH - 125 cbackSpe4x155SOH - 124 cbackSpe4x155TPOH - 125, 126
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
145
Spectra-4x155 (PM5316) Driver Manual
SPE4X155_EVENT_LOH_AIS_AUX - 157 SPE4X155_EVENT_LOH_APSBF - 157 SPE4X155_EVENT_LOH_BIPE - 157 SPE4X155_EVENT_LOH_COAPS - 157 SPE4X155_EVENT_LOH_COSSM - 157 SPE4X155_EVENT_LOH_RDI - 157 SPE4X155_EVENT_LOH_RDI_AUX - 157 SPE4X155_EVENT_LOH_REI - 157 SPE4X155_EVENT_LOH_SD - 157, 158 SPE4X155_EVENT_LOH_SD_AUX - 158 SPE4X155_EVENT_LOH_SF - 157, 158 SPE4X155_EVENT_LOH_SF_AUX - 158 SPE4X155_EVENT_RPOH_AIS - 158, 159, 160 SPE4X155_EVENT_RPOH_AIS_AUX - 158 SPE4X155_EVENT_RPOH_AISC - 159, 160 SPE4X155_EVENT_RPOH_AISC_AUX - 159 SPE4X155_EVENT_RPOH_BIPE - 160 SPE4X155_EVENT_RPOH_COMA - 161 SPE4X155_EVENT_RPOH_CONCAT - 160 SPE4X155_EVENT_RPOH_COPSL - 162 SPE4X155_EVENT_RPOH_DISCOPA - 160 SPE4X155_EVENT_RPOH_ERDI_AUX - 159 SPE4X155_EVENT_RPOH_ESE - 161 SPE4X155_EVENT_RPOH_ILLJREQ - 160 SPE4X155_EVENT_RPOH_ILLPTR - 162 SPE4X155_EVENT_RPOH_INVNDF - 160 SPE4X155_EVENT_RPOH_LOM - 159, 161 SPE4X155_EVENT_RPOH_LOM_AUX - 159 SPE4X155_EVENT_RPOH_LOP - 158, 159, 160 SPE4X155_EVENT_RPOH_LOP_AUX - 158 SPE4X155_EVENT_RPOH_LOPC - 159 SPE4X155_EVENT_RPOH_LOPC_AUX - 159 SPE4X155_EVENT_RPOH_NDF - 161 SPE4X155_EVENT_RPOH_NEWPTR - 159 SPE4X155_EVENT_RPOH_NPJ - 161 SPE4X155_EVENT_RPOH_NSE - 161 SPE4X155_EVENT_RPOH_PERDI - 160 SPE4X155_EVENT_RPOH_PPJ - 161 SPE4X155_EVENT_RPOH_PRDI - 160 SPE4X155_EVENT_RPOH_PREI - 160 SPE4X155_EVENT_RPOH_PSE - 161
SPE4X155_EVENT_RPOH_PSLM - 158, 161 SPE4X155_EVENT_RPOH_PSLM_AUX - 158 SPE4X155_EVENT_RPOH_PSLU - 158, 161 SPE4X155_EVENT_RPOH_PSLU_AUX - 158 SPE4X155_EVENT_RPOH_RDI_AUX - 158 SPE4X155_EVENT_RPOH_TIM - 159, 161 SPE4X155_EVENT_RPOH_TIM_AUX - 159 SPE4X155_EVENT_RPOH_TIU - 159, 161 SPE4X155_EVENT_RPOH_TIU_AUX - 159 SPE4X155_EVENT_RPOH_UNEQ - 161 SPE4X155_EVENT_SOH_BIPE - 155 SPE4X155_EVENT_SOH_LOF - 156 SPE4X155_EVENT_SOH_LOF_AUX - 156 SPE4X155_EVENT_SOH_LOS - 156 SPE4X155_EVENT_SOH_LOS_AUX - 156 SPE4X155_EVENT_SOH_OOF - 156 SPE4X155_EVENT_SOH_OOF_AUX - 156 SPE4X155_EVENT_SOH_TIM - 156 SPE4X155_EVENT_SOH_TIU - 156 SPE4X155_EVENT_TPOH_AIS - 162, 163 SPE4X155_EVENT_TPOH_AIS_AUX - 162 SPE4X155_EVENT_TPOH_AISC - 162, 163 SPE4X155_EVENT_TPOH_AISC_AUX - 162 SPE4X155_EVENT_TPOH_BIPE - 163 SPE4X155_EVENT_TPOH_COMA - 164 SPE4X155_EVENT_TPOH_CONCAT - 164 SPE4X155_EVENT_TPOH_DISCOPA - 164 SPE4X155_EVENT_TPOH_ESE - 163 SPE4X155_EVENT_TPOH_ILLJREQ - 164 SPE4X155_EVENT_TPOH_ILLPTR - 164 SPE4X155_EVENT_TPOH_INVNDF - 164 SPE4X155_EVENT_TPOH_LOM - 162, 164 SPE4X155_EVENT_TPOH_LOM_AUX - 162 SPE4X155_EVENT_TPOH_LOP - 162, 163 SPE4X155_EVENT_TPOH_LOP_AUX - 162 SPE4X155_EVENT_TPOH_LOPC - 162, 163 SPE4X155_EVENT_TPOH_LOPC_AUX - 162 SPE4X155_EVENT_TPOH_NDF - 164 SPE4X155_EVENT_TPOH_NEWPTR - 163 SPE4X155_EVENT_TPOH_NPJ - 163 SPE4X155_EVENT_TPOH_NSE - 164
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
146
Spectra-4x155 (PM5316) Driver Manual
SPE4X155_EVENT_TPOH_PPJ - 163 SPE4X155_EVENT_TPOH_PSE - 164 SPE4X155_EVENT_TPOH_RDI - 163 SPE4X155_EVENT_TPOH_REI - 163 max SPE4X155_MAX_DELAY - 145 SPE4X155_MAX_DEVS - 30, 31, 146, 148, 149 SPE4X155_MAX_DPV_BUF - 146 SPE4X155_MAX_INIT_PROFS - 31, 146 SPE4X155_MAX_ISV_BUF - 146 SPE4X155_MAX_POLL - 145 mode SPE4X155_MOD_IDLE - 30, 49, 56, 57, 58, 59 SPE4X155_MOD_READY - 30, 49, 56, 57, 58, 59, 60 SPE4X155_MOD_START - 30, 49, 55, 56 poll SPE4X155_ISR_MODE - 31, 105 SPE4X155_POLL_MODE - 105 SPE4X155_ACTIVE - 30, 50, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 121, 122, 123, 124, 125, 126, 127 SPE4X155_INACTIVE - 30, 50, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 110, 111, 112, 115 SPE4X155_NO_TERM - 72, 77, 84, 89 SPE4X155_PRESENT - 30, 50, 60, 61, 63, 64, 65, 66, 67, 120 SPE4X155_START - 30, 50 SPE4X155_SUCCESS - 55, 56, 57, 58, 59, 61, 62, 63, 64, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122 SPE4X155_TERM - 72, 77, 84, 89 SPE4X155_TERM_WITH_AUTO_INSERT - 77, 84, 89
driver
example file spe4x155_app.c - 141 spe4x155_app.h - 141 spe4x155_debug.c - 141 spe4x155_debug.h - 142 inc file spe4x155_api.h - 141, 151, 152 spe4x155_defs.h - 141, 146 spe4x155_err.h - 141, 146 spe4x155_fns.h - 141 spe4x155_hw.h - 141, 144, 145, 151, 152 spe4x155_rtos.h - 141, 142, 143, 144, 151, 152 spe4x155_strs.h - 141 spe4x155_typs.h - 141, 144 src file spe4x155_api1.c - 140, 151, 152 spe4x155_api2.c - 140, 151 spe4x155_hw.c - 140, 151, 152 spe4x155_isr.c - 140, 152 spe4x155_prof.c - 140 spe4x155_rtos.c - 140, 151, 152 spe4x155_stat.c - 140, 151 spe4x155_util.c - 140, 151
E
enumeration
eSPE4X155_DEV_STATE - 51 eSPE4X155_MOD_STATE - 49 eSPE4X155_POLL - 32, 51 eSPE4X155_TERM - 72, 77, 84, 89
error
errDevice - 50, 54, 60 errModule - 31, 49, 54
G
global variables
D
device
deviceHandle - 53 numDevs - 49 stateDevice - 30, 50, 51, 54 spe4x155Mdb - 54, 149
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
147
Spectra-4x155 (PM5316) Driver Manual
M
module
stateModule - 30, 49, 54
psrcSlot - 68, 69, 70, 71 pthreshCntr - 111 pthreshold - 109, 110, 111
poll
P
pointers
aptr - 90 palmIO - 116, 117 palmLOH - 118 palmRPOH - 118, 119 palmSOH - 117 palmTPOH - 119 pblock - 65, 66 pcfgPrbs - 99, 100, 102, 103 pcfgSD - 82 pcfgSF - 82 pcnt - 112 pcntLOH - 113 pcntPJ - 115 pcntRPOH - 114 pcntSOH - 113 pcntTPOH - 115 pddb - 50, 54, 115 pdestSlot - 68, 69, 70, 71 pdiv - 61, 62 pdpv - 123, 124, 125, 126, 127, 136, 146 pdst - 133 perrModule - 31 pfirstByte - 132 pinitProfs - 50 pISV - 135 pmask - 66, 106, 107 pmem - 133 pmiv - 55 pnumDestSlots - 69, 70 pperrDevice - 60 pProfile - 58 pProfileNum - 58 pPSL - 85 psrc - 133
pollISR - 31, 32
porting functions
sysSpe4x155BufferStart - 53, 134, 143 sysSpe4x155BufferStop - 136, 143 sysSpe4x155DPRTask - 27, 28, 29, 109, 138, 145 sysSpe4x155DPVBufferGet - 109, 135, 143 sysSpe4x155DPVBufferRtn - 123, 136, 144 sysSpe4x155ISRHandler - 27, 28, 29, 108, 129, 130, 131, 145 sysSpe4x155ISRHandlerInstall - 29, 129, 130, 145 sysSpe4x155ISRHandlerRemove - 129, 131, 145 sysSpe4x155ISVBufferGet - 53, 134, 143 sysSpe4x155ISVBufferRtn - 53, 135, 143 sysSpe4x155MemAlloc - 132, 142 sysSpe4x155MemCpy - 133, 143 sysSpe4x155MemFree - 132, 142 sysSpe4x155MemSet - 133, 143 sysSpe4x155PollBit - 129 sysSpe4x155PreemptDisable - 137, 138, 143 sysSpe4x155PreemptEnable - 137, 138, 143 sysSpe4x155Read - 64, 65, 128, 144, 149, 150 sysSpe4x155TimerSleep - 136, 137, 143 sysSpe4x155Write - 65, 66, 128, 144
S
structures
sSPE4X155_CFG_CLK - 32, 33, 52 sSPE4X155_CFG_CNT - 33, 34, 52, 111 sSPE4X155_CFG_PRBS - 43, 52, 99, 102, 103 sSPE4X155_CFG_SFSD - 33, 34, 52, 82 sSPE4X155_DDB - 50, 115, 149, 150 sSPE4X155_DIV - 32, 50, 58, 61, 62 sSPE4X155_DPV - 54, 135, 136 sSPE4X155_HNDL - 53, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
148
Spectra-4x155 (PM5316) Driver Manual
sSPE4X155_ISV - 53, 134, 135 sSPE4X155_MASK - 35, 52, 53, 106, 107, 109, 110, 111 sSPE4X155_MDB - 49 sSPE4X155_MIV - 31, 55 sSPE4X155_STAT_CNT - 41, 42, 43, 112, 113, 114, 115 sSPE4X155_STAT_CNT_LOH - 41, 42, 113 sSPE4X155_STAT_CNT_PJ - 41, 43, 115 sSPE4X155_STAT_CNT_RPOH - 41, 42, 114 sSPE4X155_STAT_CNT_SOH - 41, 113
sSPE4X155_STAT_CNT_TPOH - 41, 42, 115 sSPE4X155_STATUS - 45, 46, 47, 48, 116, 117, 118, 119 sSPE4X155_STATUS_IO - 45, 116 sSPE4X155_STATUS_LOH - 45, 47, 118 sSPE4X155_STATUS_RPOH - 45, 47, 118 sSPE4X155_STATUS_SOH - 45, 46, 117 sSPE4X155_STATUS_TPOH - 45, 48, 119 sSPE4X155_TSLOT - 43, 68, 69, 70, 71 sSPE4X155_USR_CTXT - 123, 124, 125, 126, 127, 146
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-2001693 Issue 1
149

▲Up To Search▲

Price & Availability of 2001693

	To Download 2001693 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .