PMC-Sierra PM5358 S/UNI 4x622 File Organization

PM5358 S/UNI-4x622 Driver Manual

Appendix A: Coding Conventions

Proprietary and Confidential to PMC-Sierra, Inc. 123

Document ID: PMC-2010419, Issue 1

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 Function s

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.

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