File Organization, Functions | PMC-Sierra PM5358 S/UNI 4x622

PM5358 S/UNI-4x622 Driver Manual

Appendix A: Coding Conventions

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: suni4x622Add() 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: sysSuni4x622Read() 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: utilSuni4x622ValidateChan() 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 suni4x622Mdb 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

File Organization

The next table 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 convey their purpose with a minimum number of characters.

Proprietary and Confidential to PMC-Sierra, Inc.	123
Document ID: PMC-2010419, Issue 1

Image 123

PMC-Sierra PM5358 S/UNI 4x622 manual File Organization, Functions, Variables

Contents

PM5358 UNI-4X622 Issue 1 April Revision History Issue April Document createdAudience References Contacting PMC-Sierra Legal Issues Table of Contents Updating the Configuration of a Device suni4x622Update Setting Payload configuration parameters suni4x622PyldCfg 100 112 128 List of Figures List of Tables UNI-4x622 Global Line Interface Configuration Introduction Application Programming Interface Driver External Interfaces Main Components Real-Time OS InterfaceHardware Interface Rtos Module Data-Block and Devices Data-Blocks Interrupt-Service Routine Alarms, Status and CountsDeferred-Processing Routine Line Overhead Interface ConfigurationAPS Configuration Section Overhead Module States Software States Device States Module States Processing Flows Module ManagementDevice Management Suni4x622AddInitProfile Interrupt Servicing Suni4x622ISR and suni4x622DPR Calling suni4x622ISR Calling suni4x622Poll Calling suni4x622DPR Polling Service Model Constants Structures Passed by the ApplicationModule Initialization Vector MIV Device Initialization Vector DIV ISR Enable/Disable Mask Line alarm signal Interrupt mask for Fifo ConfigurationLoss of signal Section BIP error Signal Failure Line BIP errorLine REI error Signal Defect Rx CP Fifo overrun Tx FP Fifo underrun Rx FP Fifo overrun Module Data Block MDB Structures in the Driver’s Allocated Memory Device Data Block DDB Base address of the device Interrupt Enable MaskDevice State can be one of the following PRESENT, Active or Inactive Device-wide Global Configuration Per-Channel Line Overhead LOH Configuration Per-Channel Section Overhead SOH Configuration Transmitted stream Per-Channel Receive Path Overhead Rpoh ConfigurationPer-Channel Transmit Path Overhead Tpoh Configuration Control of the persistence of the RDI asserted into Controls whether Pais will disable Eprdi insertion Controls whether Path signal label mismatch can causeControls whether unequipped path signal label can cause Controls whether LOS,LOF or Lais will disable Eprdi Per-Channel Payload Processor Configuration Per-Channel Clock Interface Configuration Per-Channel Fifo Configuration Per-Channel Ralrm Configuration Per-Channel Line Interface ConfigurationClock configuration block Device-wide System Interface Configuration Ralrm configuration block Device-Wide Line Interface Configuration Section Overhead SOH Status Receive Path Overhead Rpoh Status Line Overhead LOH Status Clock Status Payload Processor Status Line Interface Status Section BIP error counterTfclk active Refclka active Line Overhead LOH Counter Receive Path Overhead Rpoh CounterPayload Processor Pyld Counter Interrupt-Service Vector ISV Structures Passed through Rtos BuffersDeferred-Processing Vector DPV Global Variable Prototype Inputs Outputs Returns Module ManagementOpening the Driver Module suni4x622ModuleOpen Closing the Driver Module suni4x622ModuleClose Side Effects Starting the Driver Module suni4x622ModuleStartStopping the Driver Module suni4x622ModuleStop Valid States Profile Management Adding an Initialization Profile suni4x622AddInitProfileGetting an Initialization Profile suni4x622GetInitProfile Device Management Adding a Device suni4x622AddSide Effects None Deleting a Device suni4x622Delete Initializing a Device suni4x622InitPrototype Inputs Outputs Returns Valid States Side Effects Updating the Configuration of a Device suni4x622Update Resetting a Device suni4x622ResetSide Effects Changes the Device state to SUNI4x622INACTIVE Changes the Device state to SUNI4x622INACTIVE Activating a Device suni4x622ActivateDe-Activating a Device suni4x622DeActivate Changes the Device state to SUNI4x622ACTIVE Device Read and Write Reading from Device Registers suni4x622ReadWriting to Device Registers suni4x622Write Reading from a block of Device Registers suni4x622ReadBlock Writing to a Block of Device Registers suni4x622WriteBlockPrototype Inputs Writing the J0 Byte suni4x622SOHWriteJ0 Section Overhead SOH Forcing A1 Error suni4x622SOHForceA1 Forcing B1 Error suni4x622SOHForceB1 Flag to start/stop B1 error insertionForcing OOF suni4x622SOHForceOOF Line Overhead LOH Configuring SF Error Monitor suni4x622LOHSFCfgFlag to start/stop a loss of signal condition Pointer to SF configuration block Writing the K1K2 Byte suni4x622LOHWriteK1K2 Configuring SD Error Monitor suni4x622LOHSDCfg Writing the S1 Byte suni4x622LOHWriteS1 Reading the K1K2 Byte suni4x622LOHReadK1K2 Forcing B2 Error suni4x622LOHForceB2 Reading the S1 Byte suni4x622LOHReadS1Forcing Line AIS suni4x622LOHForceAIS This function forces the line RDI into the line overhead Flag to start/stop B2 error insertionPath Overhead RPOH, Tpoh Forcing Line RDI suni4x622LOHForceRDI Writing the J1 Byte suni4x622TPOHWriteJ1 Writing the New Data Flag Bits suni4x622TPOHWriteNDF Writing the C2 Byte suni4x622TPOHWriteC2 Force Path BIP-8 Errors suni4x622TPOHForceB3 Writing SS Bits suni4x622TPOHWriteSSInserting a Pointer Value suni4x622TPOHInsertTxPtr Type of Pointer Justification event Forcing Pointer Justification suni4x622TPOHForcePJForcing Path RDI suni4x622TPOHForceRDI Flag to start/stop B3 masking Flag to start/stop path Erdi insertion Forcing Path Erdi suni4x622TPOHForceERDIForcing Path Ardi suni4x622TPOHForceARDI Flag to start/stop path RDI insertion Flag to start/stop path AIS insertion Setting Payload configuration parameters suni4x622PyldCfgPayload Processor Forcing Path AIS suni4x622TPOHForceAIS Interface Configuration Resetting the Receive/Transmit Fifo suni4x622FIFOResetConfiguring the Receive and Transmit Fifo suni4x622FIFOCfg Pointer to device-wide line interface Configuring the System interface suni4x622SysIntfCfgPointer to Fifo configuration block Pointer to system interface configuration This function resets the Rfclk DLL Resetting the Tfclk DLL suni4x622IntfSysResetTDLLResetting the Rfclk DLL suni4x622IntfSysResetRDLL This function resets the Tfclk DLL Configuring APS Working/Protect Mate suni4x622APSCfg Automatic Protection Configuration Transmit path channel number Resetting APS Receive Link suni4x622APSResetRxLinkEnable or disable Function is used to reset the receive APS link APS link number Interrupt Service FunctionsResetting APS Transmit Link suni4x622APSResetTxLink Function is used to reset the transmit APS link Configuring ISR Processing suni4x622ISRConfig Getting Device Interrupt Enable Mask suni4x622GetMaskSetting Device Interrupt Enable Mask suni4x622SetMask Clearing Device Interrupt Enable Mask suni4x622ClrMask Getting SOH Interrupt Enable Mask suni4x622GetMaskSOHSide Effects May change the operation of the ISR / DPR Setting SOH Interrupt Enable Mask suni4x622SetMaskSOH Clearing SOH Interrupt Enable Mask suni4x622ClrMaskSOHMay change the operation of the ISR / DPR Setting LOH Interrupt Enable Mask suni4x622SetMaskLOH Getting LOH Interrupt Enable Mask suni4x622GetMaskLOH Getting Rpoh Interrupt Enable Mask suni4x622GetMaskRPOH Clearing LOH Interrupt Enable Mask suni4x622ClrMaskLOH Clearing Rpoh Interrupt Enable Mask suni4x622ClrMaskRPOH Setting Rpoh Interrupt Enable Mask suni4x622SetMaskRPOH Setting Pyld Interrupt Enable Mask suni4x622SetMaskPYLD Getting Pyld Interrupt Enable Mask suni4x622GetMaskPYLD Getting Fifo Interrupt Enable Mask suni4x622GetMaskFIFO Clearing Pyld Interrupt Enable Mask suni4x622ClrMaskPYLD Clearing Fifo Interrupt Enable Mask suni4x622ClrMaskFIFO Setting Fifo Interrupt Enable Mask suni4x622SetMaskFIFO INT4 suni4x622SetMaskIntfLinesSUNI4x622HNDL Prototype Inputs Outputs Side Effects May change the operation of the ISR / DPR Setting APS Interrupt Enable Mask suni4x622SetMaskAPS Getting APS Interrupt Enable Mask suni4x622GetMaskAPS Clearing APS Interrupt Enable Mask suni4x622ClrMaskAPS Polling the Interrupt Status Registers suni4x622PollPseudocode Outputs None Returns Interrupt-Service Routine suni4x622ISRDeferred-Processing Routine suni4x622DPR Pointer to ISV buffer Alarm, Status and Counts Functions Getting the Device Status suni4x622GetStatusChanGetting the Device Status suni4x622GetStatusSOH Getting the Device Status suni4x622GetStatusRPOH Getting the Device Status suni4x622GetStatusLOH Getting the Device Status suni4x622GetStatusPYLD Getting the Device Status suni4x622GetStatusIntfLine Getting the Device Counts suni4x622GetCountsSOH Getting the Device Counts suni4x622GetCountsChan Getting the Device Counts suni4x622GetCountsRPOH Getting the Device Counts suni4x622GetCountsLOH Device Diagnostics Testing Register Accesses suni4x622DiagTestRegGetting the Device Counts suni4x622GetCountsPYLD Sets loop if non-zero, else clears loop Enabling Path Diagnostic Loopbacks suni4x622DiagPathLoopEnabling Data Diagnostic Loopbacks suni4x622DiagDataLoop Enabling Line Loopbacks suni4x622DiagLineLoop INT4 suni4x622DiagSerialLoopsSUNI4x622HNDL User context from suni4x622Add Callback FunctionsNotifying the Application of SOH Events cbackSuni4x622SOH Will inhibit the flow of active data Notifying the Application of Rpoh Events cbackSuni4x622RPOH Notifying the Application of LOH Events cbackSuni4x622LOH Notifying the Application of Pyld Events cbackSuni4x622PYLD Notifying the Application of Fifo Events cbackSuni4x622FIFO Format Prototype Inputs Outputs Returns Device I/OReading from a Device Register sysSuni4x622Read Writing to a Device Register sysSuni4x622Write Outputs None Installing the ISR Handler sysSuni4x622ISRHandlerInstallSystem-Specific Interrupt Servicing Polling a Bit sysSuni4x622PollBit Format Prototype Inputs Outputs Returns Pseudocode ISR Handler sysSuni4x622ISRHandlerDPR Task sysSuni4x622DPRTask Pseudocode Begin Vector table Removing the ISR Handler sysSuni4x622ISRHandlerRemove Copy Memory sysSuni4x622MemCpy Memory Allocation / De-AllocationAllocating Memory sysSuni4x622MemAlloc Initialize Memory sysSuni4x622MemSet Inputs None Outputs Returns Success = Buffer ManagementFreeing Memory sysSuni4x622MemFree Starting Buffer Management sysSuni4x622BufferStart Pointer to a ISV buffer Getting an ISV Buffer sysSuni4x622ISVBufferGetReturning an ISV Buffer sysSuni4x622ISVBufferRtn Getting a DPV Buffer sysSuni4x622DPVBufferGet Stopping Buffer Management sysSuni4x622BufferStop TimersSleeping a Task sysSuni4x622TimerSleep Returning a DPV Buffer sysSuni4x622DPVBufferRtn Preemption key returned by sysSuni4x622PreemptDis Disabling Preemption sysSuni4x622PreemptDisableRe-Enabling Preemption sysSuni4x622PreemptEnable Preemption Porting Assumptions Driver Porting ProceduresDriver Source Files To port the S/UNI-4x622 driver to your platform To port the driver’s OS extensions Procedure 1 Porting Driver OS Extensions To port the driver’s application-specific elements Procedure 2 Porting Drivers to Hardware PlatformsProcedure 3 Porting Driver Application-Specific Elements To port the driver to your hardware platform To build the driver Procedure 4 Building the DriverThis section describes how to build the driver DPR task stack size, in bytes 8192 Naming Conventions Variable Type Definitions Macros ConstantsStructures File Organization FunctionsVariables Device specific configuration functions defined API DiagnosticsDevice diagnostic functions Interface configuration functions for connecting Failure Error while installing interruptsInvalid ISR/polling mode Success Line Overhead Events LOH Section Overhead Events SOH Path Overhead Events Rpoh Payload Events Pyld Line Interface Events IntflineSystem Interface Events Sysintf Automatic Protection Switching Events APS List of Terms Acronyms Index Callbacks Device Enumerated types System-specific functions