Access-Layer Components HSS-Access IxHssAcc API | Intel IXP400

	Intel® IXP400 Software
Access-Layer Components:	13
HSS-Access (IxHssAcc) API	13

This chapter describes the Intel® IXP400 Software v2.0’s “HSS-Access API” access-layer component.

13.1What’s New

There are no changes or enhancements to this component in software release 2.0.

13.2Overview

The IxHssAcc component provides client applications with driver-level access to the High-Speed Serial (HSS) and High-Level Data Link Control (HDLC) coprocessors available on NPE A. This API and its supporting NPE-based hardware acceleration enable the Intel® IXP400 Softwareto support packetized or channelized TDM data communications.

This chapter provides the details of how to use IxHssAcc to:

•Initialize and configure the HSS and HDLC coprocessors.

•Allocate buffers for transmitting and receiving data.

•Connect and enable packetized service and/or channelized service.

•Handle the transmitting and receiving process.

•Disconnect and disable the services.

Programmer’s Guide	IXP400 Software Version 2.0	April 2005
	Document Number: 252539, Revision: 007	189

Image 189

Intel IXP400 manual Access-Layer Components HSS-Access IxHssAcc API, What’s New

Contents

Programmer’s Guide Intel IXP400 Software IXP400 Software Version Intel IXP400 Software Contents 1.1 100 118 152 Contents Access-Layer Components 225 17.9 Operating System Adsl Driver Figures 102 Tables AQM 300 Date Revision Description Revision History Versions Supported by this Document Introduction1Hardware Supported by this Release Intended Audience How to Use this Document About the ProcessorsChapters Description Document Title Document # Related Documents Acronyms Document Title Document #Acronym Description CPU HSS MSB SIP High-Level Overview Software Architecture Overview Software Architecture Overview Deliverable Model Access Library Source Code Documentation Operating System SupportDevelopment Tools Ixposal Include Src Ixp400xscalesw Release Directory Structure \---include +---npeMh Threading and Locking Policy Polled and Interrupt OperationStatistics and MIBs Global Dependencies Global Dependency Chart This page is intentionally left blank Buffer Management What’s NewOverview Intel IXP400 Software Buffer Flow Buffer Management Raw Buffers Ixpbuf User Interface Ixpbuf Structure and Macros Ixpbuf Structure Osal Ixpbuf structure and macros API User Interface to Ixpbuf Ixmbuf OS-Dependent Buffer Format Pool Management Fields Ixne IXP400 NPE Shared Structure Ixpbuf ixctrl Structure Ixpbuf NPE Shared Structure Mapping of Ixmbuf to Shared Structure Internal Ixmbuf Field Format Sheet 1 Ixmbuf StructureIxnext Ixosalmbufnextbufferinpktptr Ixreserved Field / Macro Purpose Used by Access-Layer? Internal Ixmbuf Field Format Sheet 2Ixmbuf Field Details Sheet 1 Mapping to OS Native Buffer Types VxWorks* Mblk BufferIxmbuf Field Details Sheet 2 Ixmbuf to Mblk Mapping Linux* skbuff Buffer Buffer Translation Functions Following fields will get updated in the skbuffer Tx Path Caching Strategy Rx Path Caching Strategy SummaryBuffer Management Tx Cache Flushing Example Intel IXP400 Software This page is intentionally left blank IxAtmdAcc Component Features Access-Layer Components ATM Driver Access IxAtmdAcc API Access-Layer Components ATM Driver Access IxAtmdAcc API Configuration Services Utopia Port-Configuration ServiceATM Traffic-Shaping Services VC-Configuration Services Transmission Services Buffer Transmission for a Scheduled Port Scheduled Transmission Schedule Table Description Transmit-Done Processing Transmission Triggers Tx-Low Notification Transmit Done Based on a Threshold Level Tx Done Recycling Using a Threshold Level Transmit Disconnect Tx Done Recycling Using a Polling Mechanism Tx Disconnect Receive Services Receive Triggers Rx-Free-Low Notification Receive ProcessingReceive Based on a Threshold Level Rx Using a Threshold Level Receive Disconnect RX Using a Polling Mechanism Buffer Contents Buffer ManagementBuffer Allocation Ixpbuf Fields of Available Buffers for Reception Ixpbuf Fields Required for TransmissionIxpbuf Fields Modified During Reception Sheet 1 Field Description API-Usage Errors Error HandlingBuffer-Size Constraints Buffer-Chaining Constraints Real-Time Errors Real-Time ErrorsCause Consequences and Side Effects Corrective Action Access-Layer Components ATM Manager IxAtmm API IxAtmm Component FeaturesIxAtmm Overview Utopia Level-2 Port Initialization Access-Layer Components ATM Manager IxAtmm API ATM-Port Management Service Model Services Provided by Ixatmm Tx/Rx Control Configuration Configuration of Traffic Control Mechanism Dependencies Error HandlingManagement Interfaces Memory Requirements Performance IxAtmSch Component Features Access-Layer Components ATM Transmit Scheduler IxAtmSch Access-Layer Components ATM Transmit Scheduler IxAtmSch API Supported Traffic TypesTraffic Type Supported Num VCs Connection Admission Control CAC Function Schedule Table Scheduling and Traffic Shaping Schedule Service Model Minimum Cells Value minCellsToScheduleMaximum Cells Value maxCells Timing and Idle Cells Data Memory Code SizeIxAtmSch Data Memory Usage Per VC Data Per Port Data Total Latency Access-Layer Components Security IxCryptoAcc API Access-Layer Components Security IxCryptoAcc API IxCryptoAcc API ArchitectureIxCryptoAcc Interfaces Basic API Flow Basic IxCryptoAcc API Flow Context Registration and the Cryptographic Context Database Intel IXP400 Software IxCryptoAcc API Call Process Flow for CCD Updates Memory Requirements Buffer and Queue ManagementIxCryptoAcc Data Memory Usage Sheet 1 Structure Size in Bytes Total Size in Bytes IxCryptoAcc Data Memory Usage Sheet 2 Dependencies IxCryptoAccHashKeyGenerate Other API Functionality Endianness IPSec ServicesImport and Export of Cryptographic Technology IPSec Background and Implementation IxCryptoAcc, NPE and IPSec Stack Scope Relationship Between IPSec Protocol and Algorithms IPSec Packet Formats Reference ESP Dataflow Authentication Header ESP Data Flow Reference AH Dataflow IPSec API Call Flow Hardware Acceleration for IPSec Services IPSec API Call Flow Hmac with Key Size Greater Than 64 Bytes Special API Use Cases CCM Operation Flow AES CBC Encryption For MIC WEP Services IPSec Assumptions, Dependencies, and LimitationsWEP Background and Implementation WEP Frame with Request Parameters Hardware Acceleration for WEP Services IxCryptoAccNpeWepPerform WEP API Call FlowIxCryptoAccXscaleWepPerform NPE Microcode Images WEP Perform API Call Flow Combined Mode Operations AuthenticationSSL and TLS Protocol Usage Models Encryption/Decryption Encryption Algorithms Supported Encryption and Authentication AlgorithmsSupported Encryption Algorithms Cipher Key Sizes Parity Bit Actual Key Size Cipher Modes Counter Mode CTRElectronic Code Book ECB Cipher Block Chaining CBC Authentication Algorithms Supported Authentication AlgorithmsAuthentication Algorithm Data Block Size Bits Key Size Bits 114 Document Number 252539, Revision Access-Layer Components DMA Access Driver IxDmaAcc API FeaturesAssumptions Access-Layer Components DMA Access Driver IxDmaAcc API DMA Access-Layer API IxDmaAcc Component Overview IxDmaAccDescriptorManager Parameters Description Source Address Transfer ModeDestination Address Transfer Width Transfer Length Addressing Modes Transfer Mode Supported ModesIncrement 122 Document Number 252539, Revision Control Flow Data Flow IxDmaAcc Control Flow DMA Initialization IxDMAcc Initialization DMA Configuration and Data Transfer DMA Transfer Operation Restrictions of the DMA Transfer Little Endian IxEthAcc Overview Access-Layer Components Ethernet Access IxEthAcc API Ethernet Access Layers Architectural Overview Access-Layer Components Ethernet Access IxEthAcc APIRole of the Ethernet NPE Microcode 4 MAC/PHY Configuration Queue ManagerLearning/Filtering Database Ethernet Access Layers Component Features Data Plane Ethernet Access Layers Block Diagram Port Initialization Ethernet Frame TransmissionTransmission Flow Transmit Buffer Management and Priority TxEnetDone Ethernet Transmit Frame Data Buffer Flow Using Chained IXOSALMBUFs for Transmission / Buffer Sizing Ethernet Frame ReceptionTx Fifo Priority Ethernet Receive Frame API Overview Receive Flow Receive Buffer Management and Priority Buffer SizingSupplying Buffers Codelet or client application Programmer’s Guide Rx Fifo Priority QoS Mode Freeing BuffersRecycling Buffers No Receive Polling Additional Receive Path Information Control Path Data-Plane EndiannessMaximum Ethernet Frame Size IxEthAcc and Secondary Components Ethernet MAC Control MAC Duplex SettingsMII I/O Frame Check Sequence Non-Promiscuous Mode Promiscuous ModeMAC Filtering 1.6 802.3x Flow Control Shared Data Structures InitializationNPE Loopback Emergency Security Port Shutdown Ixpneflags Field Format Ixosalmbuf Structure Format Queue Field Description Eth 150 Document Number 252539, Revision Ixosalmbuf Port ID Field Format Ixosalmbuf Port ID Field Values Management InformationIxpneflags.linkprot Field Values Field Bit Values Object Increment Criteria Managed Objects for Ethernet Receive Managed Objects for Ethernet Transmit IxEthDB Functional Behavior Access-Layer Components Ethernet Database IxEthDB API Access-Layer Components Ethernet Database IxEthDB API MAC Address Learning and FilteringLearning and Filtering Node Learning/Filtering General Characteristics Other MAC Learning/Filtering Usage ModelsPort Definitions Port Dependency Map Provisioning Static and Dynamic EntriesAging Database Maintenance Frame Size FilteringRecord Management Source MAC Address Firewall Filtering Example Based Upon Maximum Frame SizeMAC Address Block/Admission Invalid MAC Address Filtering 10.3.4 802.1Q Vlan Background Vlan Data in Ethernet Frames Untagged MAC Frame FormatVlan Tagged MAC Frame Format Database Records Associated With Vlan IDs Acceptable Frame Type FilteringVlan Tag Format Port-Based Vlan Membership Filtering Ingress Tagging and Tag Removal Port and VLAN-Based Egress Tagging and Tag Removal Special Conditions Egress Vlan Tagging/Untagging Behavior Matrix Tag Mode Frame Status Action 10.3.5 802.1Q User Priority / QoS Support Port ID ExtractionPriority Aware Transmission QoS on Receive for 802.1Q Tagged Frames Receive Priority Queuing QoS on Receive for Untagged Frames Priority to Traffic Class Mapping 10.3.6 802.3 / 802.11 Frame Conversion Default Priority to Traffic Class MappingBackground 802.3 and 802.11 Frame Formats IEEE802.11 Frame Format AP-STA and AP-AP Modes IEEE802.11 Frame Control FC Field Format Receive Path How the 802.3 / 802.11 Frame Conversion Feature Works Field AP to STA mode AP to AP mode To 802.11 Header Conversion RulesTransmit Path 11 to 802.3 Header Conversion Rules 10.3.6.3 802.3 / 802.11 API DetailsInput 802.11 Frame Values Output 802.3 Frame Field Values Frame Type Spanning Tree Protocol Port Settings IxEthDB APIInitialization Additional Database Features Feature SetIxEthDB Feature Set User-Defined Field Database Clear Dependencies on IxEthAcc ConfigurationPromiscuous-Mode Requirement FCS Appending 180 Document Number 252539, Revision Supported PHYs Access-Layer Components Ethernet PHY IxEthMii API PHYs Supported by IxEthMii Access-Layer Components Ethernet PHY IxEthMii API Hardware Feature Control Access-Layer Components Feature Control IxFeatureCtrl API Access-Layer Components Feature Control IxFeatureCtrl API Using the Product ID-Related FunctionsProduct ID Values Bits Description Feature Control Register Values Sheet 1 Using the Feature Control Register Functions Software Configuration Feature Control Register Values Sheet 2Component Check by Other APIs Document Number 252539, Revision 187 188 Document Number 252539, Revision Access-Layer Components HSS-Access IxHssAcc API Access-Layer Components HSS-Access IxHssAcc API Features IxHssAcc API OverviewIxHssAcc Interfaces Access-Layer Components HSS-Access IxHssAcc API Intel X S cale C ore HSS and Hdlc Theory and Coprocessor Operation HSS Output Clock Jitter and Error Characterization HSS Tx Clock Output frequencies and PPM ErrorHSS Tx Freq Pj Max ns Cj Max ns Aj Max ns HSS Frame Output Characterization Jitter DefinitionsJitter Type Jitter Definition Actual Frame Length µs High-Level API Call Flow IxHssAcc Component Dependencies Key Assumptions IxHssAccPortInit HSS Port Initialization Details 198 Document Number 252539, Revision Channelized Connect and Enable HSS Channelized OperationIxHssAccChanConnect 200 Document Number 252539, Revision Channelized Connect Channelized Tx/Rx Methods Polled CallBack Channelized Transmit and Receive HSS Packetized Operation Packetized Connect and EnableChannelized Disconnect IxHssAccPktPortConnect Document Number 252539, Revision 205 Packetized Connect Packetized Tx Document Number 252539, Revision 207 Packetized Transmit Packetized Rx Document Number 252539, Revision 209 Packetized Receive Data Flow in Packetized Service 13.6.5 56-Kbps, Packetized Raw ModeBuffer Allocation Data-Flow Overview Packetized Disconnect 212 Document Number 252539, Revision HSS Packetized Receive Buffering HSS Packetized Transmit Buffering Data Flow in Channelized Service Document Number 252539, Revision 215 HSS Channelized Receive Operation HSS Channelized Transmit Operation 218 Document Number 252539, Revision Access-Layer Components NPE-Downloader IxNpeDl API Microcode ImagesLoading NPE Microcode from a File Versus Loaded from Memory Standard Usage Example Access-Layer Components NPE-Downloader IxNpeDl APINPE Microcode Library Customization NPE Image Compatibility Image Name Description NPE-A Images NPE-C Images Sheet 1 NPE-B Images Custom Usage Example IxNpeDl UninitializationNPE-C Images Sheet 2 Deprecated APIs Access-Layer Components NPE Message Handler IxNpeMh API Initializing the IxNpeMh Access-Layer Components NPE Message Handler IxNpeMh APIInterrupt-Driven Operation Polled Operation Sending an NPE Message Uninitializing IxNpeMh Client Sending an NPE Message with ResponseCustomer / Demo Code IxNpeMh IxNpeMh Client Customer / Demo Code Receiving Unsolicited Messages from NPE to Software Client IxNpeMh Component Dependencies 232 Document Number 252539, Revision Access-Layer Components Parity Error Notifier IxParityENAcc IntroductionBackground Scrubbing/Memory Scrub Network Processing Engines AHB Queue Manager AQM Switching Coprocessor in NPE B SwcpDDR Sdram Memory Controller Unit MCU Expansion Bus Controller Interrupt Bit Default Priority Software Parity Error InterruptsInterrupt Prioritization Secondary Effects of Parity Interrupts Features Feature Hardware Component Software Support RecoverableIxParityENAcc API Details IxParityENAcc API Usage Scenarios IxParityENAcc Dependency Diagram Parity Error Notification Sequence Summary Parity Error Notification Scenario Interrupt Bit Source API Invoked by Parity Error Interrupt Deassertion Conditions Sheet 1 Parity Error Interrupt Deassertion Conditions Sheet 2 Summary Parity Error Recovery Scenario Parity Error Notification Detailed Scenarios Summary Parity Error Prevention Scenario Data Abort with No Parity Error Data Abort followed by Unrelated Parity Error Notification Data Abort Caused by Parity Error Data Abort with both Related and Unrelated Parity Errors Access-Layer Components Performance Profiling IxPerfProfAcc Intel XScale Core PMU Counter Buffer Overflow Internal Bus PMU Idle-Cycle Counter Utilities ‘Xcycle’ IxPerfProfAcc Dependencies Interrupt Handling Threading Using the API Event and Clock Counting API Usage for Intel XScale Core PMU 254 Document Number 252539, Revision Display Performance Counters Time-Based Sampling Display Clock Counter Iii. Print out the first five elements Event-Based Sampling 258 Document Number 252539, Revision C0112788 No lower symbol found. Module kernel Using Intel XScale Core PMU to Determine Cache Efficiency Internal Bus PMU IxPerfProfAccBusPmuStart Perform the same calculation for the rest of the PECs Xcycle Idlecycle Counter Display Xcycle Measurement Access-Layer Components Queue Manager IxQMgr API Access-Layer Components Queue Manager IxQMgr API Features and Hardware Interface Document Number 252539, Revision 267 AQM Configuration Attributes Configuration ValuesDispatcher Attribute Description Values Dispatcher Modes 270 Document Number 252539, Revision AQM Dispatcher in Context of a Polling Mechanism Livelock Prevention Document Number 252539, Revision 273 274 Document Number 252539, Revision IxSspAcc API Details Access-Layer Components Synchronous Serial Port IxSspAcc IxSspAcc Dependencies Interrupt Mode IxSspAcc API Usage ModelsInitialization and General Data Model 278 Document Number 252539, Revision Interrupt Scenario Polling Mode Init Transmit Receive 282 Document Number 252539, Revision Access-Layer Components Time Sync IxTimeSyncAcc API Access-Layer Components Time Sync IxTimeSyncAcc API Ieee 1588 PTP Protocol OverviewSynchronization Sequence Overview Ieee 1588 Hardware Assist Block Detailed Information Block Diagram of Intel IXP46X Network Processor IPv6 and VLAN-Tagged Ethernet Frames Hardware Feature Options Default State IxTimeSyncAcc IxTimeSyncAcc API DetailsIeee 1588 PTP Client Application Additional Hardware Information Document Number 252539, Revision 289 Interrupt Mode Operations IxTimeSyncAcc API Usage ScenariosPolling for Transmit and Receive Timestamps Interrupt Servicing of Target Time Reached Condition Polled Mode Operations Polling for Auxiliary Snapshot Values Interface Description Access-Layer Components UART-Access IxUARTAcc API Fifo Versus Polled Mode Access-Layer Components UART-Access IxUARTAcc APIUart / OS Dependencies Uart Services Models 296 Document Number 252539, Revision USB Controller Background Access-Layer Components USB Access ixUSB API IN, OUT, and Setup Token Packet Format Access-Layer Components USB Access ixUSB APIPacket Formats SOF Token Packet Format Data Packet Format Transaction FormatsHandshake Packet Format Bits 023 Bytes Isochronous Transaction Formats Bulk Transaction FormatsAction Token Packet Data Packet Handshake Packet Action Token Packet Data Packet Control Transaction Formats, Set-Up Stage Control Write SetupControl Transaction Formats Interrupt Transaction Formats IxUSB Setup Requests API interfaces Available for Access LayerIxUSB API Interfaces Request Name Host-Device Request Summary Sheet 1 Host-Device Request Summary Sheet 2 Configuration IxUSB Endpoint Stall Feature IxUSB Send and Receive RequestsFrame Synchronization Stall on OUT Transactions IxUSB Error Handling Error due to unknown reasons Detailed Error Codes USB Dependencies USB Data Flow Codelets ATM Codelet IxAtmCodeletCodelets DMA Access Codelet IxDmaAccCodelet Crypto Access Codelet IxCryptoAccCodeletEthernet Access Codelet IxEthAccCodelet Ethernet AAL-5 Codelet IxEthAal5App Parity Error Notifier Codelet IxParityENAccCodelet HSS Access Codelet IxHssAccCodelet Performance Profiling Codelet IxPerfProfAccCodelet Time Sync Codelet IxTimeSyncAccCodeletUSB Rndis Codelet IxUSBRNDIS Operating System Abstraction Layer Osal Osal Architecture Operating System Abstraction Layer Osal OS-Dependent Module OS-Independent Core ModuleCore Module Buffer Management Module Osal Library Structure Backward Compatibility ModuleBuffer Translation Module Document Number 252539, Revision 317 C lu d e Core Module Osal Modules and Related Interfaces Osal Core Interface Sheet 1 IPC Osal Core Interface Sheet 2 Thread Buffer Management Module 24.6.3 I/O Memory and Endianness Support ModuleOsal Buffer Management Interface Osal I/O Memory and Endianness Interface Sheet 1 Ixosalmmapvirttophys Osal I/O Memory and Endianness Interface Sheet 2 Supporting a New OS Example 1. Global Memory Map Definitions Supporting New Platforms Ixstaticmap Adsl Driver Device SupportAdsl Driver Overview Adsl Line Open/Close Overview Adsl API Example of Adsl Line Open Call Sequence Limitations and Constraints 26.3 I2C Driver API Details 2C Driver IxI2cDrv I2C Driver IxI2cDrv 2C Driver IxI2cDrv Arbitration Loss Error Master-Interrupt Mode Bus Error26.4 I2C Driver API Usage Models Initialization I2C Driver IxI2cDrv Slave-Interrupt Mode Slave-Polling ModeSupport Functions Example Sequence Flows for Slave Mode Sequence Flow Diagram for Slave Transmit in Interrupt Mode Sequence Flow Diagram for Slave Receive in Polling Mode Sequence Flow Diagram for Slave Transmit in Polling Mode 26.4.3 I2C Using Gpio Versus Dedicated I2C Hardware 340 Document Number 252539, Revision Endianness in Intel IXP400 Software Basics of EndiannessEndianness in Intel IXP400 Software Nature of Endianness Hardware or Software? Endianness When Memory is Shared Software Considerations and Implications Coding Pitfalls Little-Endian/Big-EndianCasting a Pointer Between Types of Different Sizes Here is what the macro ntohl looks like in actual code Network Stacks and Protocols Macro Examples Endian Conversion Best Practices in Coding of Endian-IndependenceMacro Source Code Avoid 346 Document Number 252539, Revision Document Number 252539, Revision 347 April Reasons for Choosing a Particular LE Coherency Mode Supporting Little-Endian Mode Silicon Endianness Controls Hardware Switches MMU Intel XScale Core Endianness Mode MMU P-Attribute Bit Little-Endian Data Coherence Enable/DisableByteswapen Bit Forcebyteswap Bit PCI Bus Swap Silicon VersionsSummary of Silicon Controls Endian Hardware Summary Part Number Brief Description IXP46X network processors A-0 stepping APB Peripherals April 2005 Ethernet Access Component IxEthAcc NPE Downloader IxNpeDlNPE Message Handler IxNpeMh Ixosalmbuf Data Payload Data Plane One Half-Word-Aligned Ethernet Frame LE Address Coherent Intel XScale Core Read of IP Header LE Data Coherent Ethernet Access MIB Statistics Learning Database FunctionIntel IXP400 Software IxEthAcc and IxEthDB Summary 27.5.4 PCI Intel IXP400 Software OS AbstractionATM and HSS Intel IXP400 Software Macros VxWorks* ConsiderationsEndian Conversion Macros #defines VxWorks* Data Coherent Swap Code Software Versions Intel IXP400 Software VersionsIntel IXP400 Software Version Little-Endian Support Yes/No