PMC-Sierra PM5358 S/UNI 4x622 4.14 Callback Functions

PM5358 S/UNI-4x622 Driver Manual

Application Programming Interface

Proprietary and Confidential to PMC-Sierra, Inc. 104

Document ID: PMC-2010419, Issue 1

channel : channel number

enable : sets loop if non-zero, else clears loop

Outputs None

Returns Success = SUNI4x622_SUCCESS

Failure = SUNI4x622_ERR_INVALID_DEVICE_STATE

SUNI4x622_ERR_INVALID_DEV

SUNI4x622_ERR_INVALID_CHAN

Valid States SUNI4x622_ACTIVE

Side Effects Will inhibit the flow of active data

4.14 Callback Functions

The S/UNI-4x622 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.

The names given to the callback functions are given as examples only. The addresses of the

callback functions invoked by the suni4x622DPR function are passed during the

suni4x622Init 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 sysSuni4x622DPVBufferRtn either within the callback

function or later inside the application code.

Notifying the Application of SOH Events: cbackSuni4x622SOH

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 suni4x622Init call. If the address of the callback function was passed as a NULL at

initialization no callback will be made.

Prototype void cbackSuni4x622SOH(sSUNI4x622_USR_CTXT usrCtxt,

sSUNI4x622_DPV *pdpv)

Inputs usrCtxt : user context (from suni4x622Add)

pdpv : (pointer to) DPV that describes this event

Outputs None

Returns None

Contents

Main A Audience References Revision History Legal Issues Contacting PMC-Sierr a TABLE OF CONTENTS Page Page Page Page Page Page L Page 1 I 2 S 2.1 Driver External Interfaces Application Programming Interface Real-T ime OS Interfa ce Hardware Interface 2.2 Main Components Module Data-Block and Device(s) Data-Blocks Interrupt-Ser vice Routi n e Deferred-Processing Routine Alarms, Status and Counts Section Overhead Line Overhead Path Overhead Payload Processor Interface Configuration 2.3 Software States Module States Device States 2.4 Processing Flows Module Management Device Management PM5358 S/UNI-4x622 Driver Manual Sof tware Architecture Proprietary and Confidential to PMC-Sierra, Inc. 22 2.5 Interrupt Servicing Calling suni4x622ISR Calling suni4x622DPR Calling suni4x622Poll Page 3 D 3.1 Constants 3.2 Structures Passed by the Ap plication Module Initialization Vector: MIV Device Initialization Vector: DIV ISR Enable/Disable Mask Page Page Page Page 3.3 Structures in the Drivers Allocated Memory Module Data Block: MDB Device Data Block: DDB Page Page Page Page Page Page Page Page Page Page Page Page Page Page Page 3.4 Structures Passed through RTOS Buffers Interrupt-Service Vector: ISV Deferred-Processing Vector: DPV 3.5 Global Variable 4 A 4.1 Module Management Opening the Driver Module: suni4x622ModuleOpen Closing the Driver Module: suni4x622ModuleClose Starting the Driver Module: suni4x622ModuleSta rt Stopping the Driver Module: suni4x622ModuleStop 4.2 Profile Management Adding an Initialization Profile: suni4x622AddInitProfile Getting an Initialization Profile: suni4x622GetInitProfile Deleting an Initialization Profile: suni4x622DeleteInitProfile 4.3 Device Management Adding a Device: suni4x622Add Deleting a Device: suni4x622Delete Initializing a Device: suni4x622Init Updating the Configuration of a Device: suni4x622Update Resetting a Device: suni4x622Reset Activating a Device: suni4x622Activate De-Activating a Device: suni4x622DeActivate 4.4 Device Read and Write Reading from Device Registers: suni4x622Read Writing to Device Registers: suni4x622Write Reading from a block of Device Registers: suni4x622ReadBlock Writing to a Block of Device Registers: suni4x622WriteBlock 4.5 Section Overhead (SOH) Writing the J0 Byte: suni4x622SOHWriteJ0 Reading and Setting the Section Trace Message : suni4x622SOHTraceMsg Forcing A1 Error : suni4x622SOHForceA1 Forcing B1 Error: suni4x622SOHForceB1 Forcing OOF: suni4x622SOHForceOOF Forcing LOS: suni4x622SOHForceLOS 4.6 Line Overhead (LOH) Configuring SF Error Monitor: suni4x622LOHSFCfg Configuring SD Error Monitor: suni4x622LOHSDCfg Writing the K1K2 Byte: suni4x622LOHWriteK1K2 Reading the K1K2 Byte: suni4x622LOHReadK1K2 Writing the S1 Byte: suni4x622LOHWriteS1 Reading the S1 Byte: suni4x622LOHReadS1 Forcing Line AIS: suni4x622LOHForceAIS Forcing B2 Error: suni4x622LOHForceB2 Forcing Line RDI: suni4x622LOHForceRDI 4.7 Path Overhead (RPOH, TPOH) Retrieving and Setting the Path Trace Messages: suni4x622POHTraceMsg Writing the J1 Byte: suni4x622TPOHWriteJ1 Writing the C2 Byte: suni4x622TPOHWriteC2 Writing the New Data Flag Bits: suni4x622TPOHWriteNDF Writing SS Bits: suni4x622TPOHWriteSS Inserting a Pointer Value: suni4x622TPOHInsertTxPtr Force Path BIP-8 Errors: suni4x622TPOHForceB3 Forcing Pointer Justification: suni4x622TPOHForcePJ Forcing Path RDI: suni4x622TPOHForceRDI Forcing Path ERDI: suni4x622TPOHForceERDI Forcing Path ARDI: suni4x622TPOHForceARDI Forcing Path AIS: suni4x622TPOHForceAIS 4.8 Payload Processor Setting Payload configuration pa rameters: suni4x622PyldCfg 4.9 Interface Configuration Resetting the Receive/Transmit FIFO: suni4x622FIFOReset Configuring the Receive and Transmit FIFO: suni4x622FIFOCfg Configuring the System interface: suni4x622SysIntfCfg Configuring the Device-Wide Line interface: suni4x622IntfLineCfg Resetting the TFCLK DLL: suni4x622IntfSysResetTDLL Resetting the RFCLK DLL: suni4x622IntfSysResetRDLL 4.10 Automatic Protection Configuration Configuring APS Working/Protect Mate: suni4x622APSCfg Configuring the Source Channel for the Given Channel Receive Path: suni4x622RPCfg Configuring the Source Channel for the Given Channel Transmit Path: suni4x622TPCfg Enable or disable the channel APS cross connect: suni4x622APSXcnntCfg Resetting APS Receive Link: suni4x622APSResetRxLink Resetting APS Transmit Link: suni4x622APSResetTxLink 4.11 Interrupt Service Functions Configuring ISR Processing: suni4x622ISRConfig Getting Device Interrupt Enable Mask: suni4x622GetMask Setting Device Interrupt Enable Mask: suni4x622SetMask Clearing Device Interrupt Enable Mask: suni4x622ClrMask Getting SOH Interrupt Enable Mask: suni4x622GetMaskSOH Setting SOH Interrupt Enable Mask: suni4x622SetMaskSOH Clearing SOH Interrupt Enable Mask: suni4x622ClrMaskSOH Getting LOH Interrupt Enable Mask: suni4x622GetMaskLOH Setting LO H Interrupt Enable Mask: suni4x 622Se tMaskLOH Clearing LOH Interrupt Enable Mask: suni4x622ClrMaskLOH Getting RPOH Inte rrupt Enable Mask: suni4x622 GetMask R POH Setting RPOH Interrupt Enable Mask: suni4x622SetMaskRPOH Clearing RPOH Interrupt Enable Mask: suni4x622ClrMaskRPOH Getting PYLD Interrupt Enable Mask: suni4x622GetMaskPYLD Setting PYLD Interrupt Enable Mask: suni4x622SetMaskPYLD Clearing PYLD Interrupt Enable Mask: suni4x622ClrMaskPYLD Getting FIFO Interrupt Enable Mask: suni4x622GetMaskFIFO Setting FIFO Interrupt Enable Mask: suni4x622SetMaskFIFO Clearing FIFO Interrupt Enable Mask: suni4x622ClrMaskFIFO Getting Line Interface Interrupt Enable Mask: suni4x622GetMaskIntfLine Setting Line Interface Interrupt Enable Mask: suni4x622SetMaskIntfLine Clearing Line Interface Interrupt Enable Mask: suni4x622ClrMaskIntfLine Getting System Interface Interrupt Enable Mask: suni4x622GetMaskSysIntf Setting System Interface Interrupt Enable Mask: suni4x622SetMaskSysIntf Clearing System Interface Interrupt Enable Mask: suni4x622ClrMaskSysIntf Getting APS Interrupt Enable Mask: suni4x622GetMaskAPS Setting APS Interrupt Enable Mask: suni4x622SetMaskAPS Clearing APS Interrupt Enable Mask: suni4x622ClrMaskAPS Polling the Interrupt Status Registers: suni4x622Poll Interrupt-Service Routine: suni4x622ISR Deferred-Processing Routine: suni4x622DPR 4.12 Al ar m, Status and Counts Functions Getting the Device Status: suni4x622GetStatusChan Getting the Device Status: suni4x622GetStatusSOH Getting the Device Status: suni4x622GetStatusLOH Getting the Device Status: suni4x622GetStatusRPOH Getting the Device Status: suni4x622GetStatusIntfLine Getting the Device Status: suni4x622GetStatusPYLD Getting the Device Counts: suni4x622GetCountsChan Getting the Device Counts: suni4x622GetCountsSOH Getting the Device Counts: suni4x622GetCountsLOH Getting the Device Counts: suni4x622GetCountsRPOH Getting the Device Counts: suni4x622GetCountsPYLD 4.13 Device Diagnostics Testing Register Accesses: suni4x622DiagTestReg Enabling Line Loopbacks: suni4x622DiagLineLoop Enabling Path Diagnostic Loopbacks: suni4x622DiagPathLoop Enabling Data Diagnostic Loopbacks: suni4x622DiagDataLoop Enabling Parallel Diagnostics Loopbacks: suni4x622DiagParaLoop Enabling Serial Diagnostics Loopbacks: suni4x622DiagSerialLoop 4.14 Callback Functions Notifying the Application of SOH Events: cbackSuni4x622SOH Notifying the Application of LOH Events: cbackSuni4x622LOH Notifying the Application of RPOH Events : cbackSuni4x622RPOH Notifying the Application of PYLD Events: cbackSuni4x622PYLD Notifying the Application of SYSINTF Events: cbackSuni4x622SysIntf Notifying the Application of FIFO Events: cbackSuni4x622FIFO 5 H 5.1 Device I/O Reading from a Device Register: sysSuni4x622Read Writing to a Device Register: sysSuni4x622Write Polling a Bit: sysSuni4x622PollBit 5.2 System-Specific Interrupt Servicing Installing the ISR Handler: sysSuni4x622ISRHandlerInstall ISR Handler: sysSuni4x622ISRHandler DPR Task: sysSuni4x622DPRTask Removing the ISR Handler: sysSuni4x622ISRHandlerRemove 6 RT OS I 6.1 Memory Allocation / De-Allocation Allocating Memory: sysSuni4x622MemAlloc Initialize Memory: sysSuni4x622MemSet Copy Memory: sysSuni4x622MemCpy 6.2 Buffer Management Starting Buffer Management: sysSuni4x622BufferStart Getting an ISV Buffer: sysSuni4x622ISVBufferGet Returning an ISV Buffer: sysSuni4x622ISVBufferRtn Getting a DPV Buffer: sysSuni4x622DPVBufferGet Returning a DPV Buffer: sysSuni4x622DPVBufferRtn Stopping Buffer Management: sysSuni4x622BufferStop 6.3 Timers Sleeping a Task: sysSuni4x62 2TimerSleep 6.4 Preemption Disabling Preemption: sysSuni4x622PreemptDisable Re-Enabling Preemption: sysSuni4x622PreemptEnable 7 PORTING THE S/UNI-4X622 DRIVER 7.1 Driver Source Files 7.2 Driver Porting Procedures Procedure 1: Porting Driver OS Extensions Procedure 2: Porting Drivers to Hardware Platforms Procedure 3: Porting Driver Application-Specific Elements Procedure 4: Building the Driver A Variabl e Typ e Definitions Naming Conventions Macros Constants Structures Functions Variables File Organization Page Page A Section Overhead Events (SOH) Line Overhead Events (LOH) Path Overhead Events (RPOH) Payload Events (PYLD) Line Interface Events (INTF_LINE) System Interface Events (SYS_INTF) Automatic Protection Switching Events (APS) L A I A api functions C callbacks constants D device driver E enumerated types error M module system-specific functions