Intel IXP400 22.4.4 ixUSB Error Handling

Intel® IXP400 Software

Access-Layer Components: USB Access (ixUSB) API

April 2005 IXP400 Software Version 2.0 Programmer’s Guide

306 Document Number: 252539, Revision: 007

The second case of a STALL handshake is known as a “protocol stall” and is unique to control

pipes. Protocol stall differs from functional stall in meaning and duration.

A protocol STALL is returned during the Data or Status stage of a control transfer, and the STALL

condition terminates at the beginning of the next control transfer (Setup). Protocol stalls are usually

sent to notify the host that a particular USB command is malformed or not implemented.

22.4.4 ixUSB Error Handling

The USB API calls return the IX_FAIL error code after detecting errors. It is the responsibility of

the user to implement appropriate error handling.

Detailed error codes are used to report USB Driver errors. They are provided in the lastError field

of the USBDevice structure that must be passed by the user in every API call. When the API calls

are successful the lastError field is assigned the IX_SUCCESS value.

Figure 103. STALL on OUT Transactions

Host

OUT

Device

STALL

Bus

Request Reply

Data

B2419-01

Contents

Main April 2005 IXP400 Software Version 2.0 Programmers Guide 2 Document Number: 252539, Revision: 007 Contents Page Page Page Page Page Page Page Page Page Figures Page Tables Page Page Contents 18 Document Number: 252539, Revision: 007 Revision History Introduction 1 1.1 Versions Supported by this Document 1.2 Hardware Supported by this Release 1.3 Intended Audience 1.4 How to Use this Document 1.5 About the Processors 1.6 Related Documents 1.7 Acronyms Page Page Document Number: 252539, Revision: 007 25 Page Software Architecture Overview 2 2.1 High-Level Overview 2.2 Deliverable Model 2.3 Operating System Support 2.4 Development Tools 2.5 Access Library Source Code Documentation 2.6 Release Directory Structure Page 2.7 Threading and Locking Policy 2.8 Polled and Interrupt Operation 2.9 Statistics and MIBs 2.10 Global Dependency Chart Page Buffer Management 3 3.1 Whats New 3.2 Overview Translation Page 3.3 IXP_BUF Structure 3.3.1 IXP_BUF Structure and Macros Document Number: 252539, Revision: 007 39 Figure 6. OSAL IXP_BUF structure and macros Page Page Page 3.4 Mapping of IX_MBUF to Shared Structure 44 Document Number: 252539, Revision: 007 Figure 13. Internal Mapping of IX_MBUF to the Shared NPE Structure ixp_len ixp_pkt_len Tabl e 1 and Table 2 present IX_MBUF structure format and details. 3.5 IX_MBUF Structure ix_reserved 1st Cache line of IXP_BUF Mapping from IX_MBUF to NPE Shared Structure 2nd Cache line of IXP_BUF Document Number: 252539, Revision: 007 45 Table 1. Internal IX_MBUF Field Format (Sheet 2 of 2) Table 2. IX_MBUF Field Details (Sheet 1 of 2) 3.6 Mapping to OS Native Buffer Types 3.6.1 VxWorks* M_BLK Buffer 3.6.2 Linux* skbuff Buffer 3.7 Caching Strategy 3.7.1 Tx Path 3.7.2 Rx Path 3.7.3 Caching Strategy Summary Page Page ATM Driver Access (IxAtmdAcc) API 4 4.1 Whats New 4.2 Overview 4.3 IxAtmdAcc Component Features Page 4.4 Configuration Services 4.4.1 UTOPIA Port-Configuration Service 4.4.2 ATM Traffic-Shaping Services 4.4.3 VC-Configuration Services 4.5 Transmission Services 4.5.1 Scheduled Transmission 4.5.1.1 Schedule Table Description 4.5.2 Transmission Triggers (Tx-Low Notification) 4.5.2.1 Transmit-Done Processing Page 4.5.2.2 Transmit Disconnect 4.5.3 Receive Services 4.5.3.1 Receive Triggers (Rx-Free-Low Notification) 4.5.3.2 Receive Processing Page 4.5.3.3 Receive Disconnect 4.5.4 Buffer Management 4.5.4.1 Buffer Allocation 4.5.4.2 Buffer Contents Page 4.5.5 Error Handling 4.5.5.2 Real-Time Errors ATM Manager (IxAtmm) API 5 5.1 Whats New 5.2 IxAtmm Overview 5.3 IxAtmm Component Features 5.4 UTOPIA Level-2 Port Initialization 5.5 ATM-Port Management Service Model Page 5.6 Tx/Rx Control Configuration Page 5.7 Dependencies 5.8 Error Handling 5.9 Management Interfaces 5.10 Memory Requirements Page ATM Transmit Scheduler (IxAtmSch) API 6 6.1 Whats New 6.2 Overview 6.3 IxAtmSch Component Features Page 6.4 Connection Admission Control (CAC) Function 6.5 Scheduling and Traffic Shaping 6.5.1 Schedule Table 6.5.1.1 Minimum Cells Value (minCellsToSchedule) 6.5.1.2 Maximum Cells Value (maxCells) 6.5.2 Schedule Service Model 6.5.3 Timing and Idle Cells 6.6 Dependencies 6.7 Error Handling 6.8 Memory Requirements 6.8.1 Code Size 6.8.2 Data Memory 6.9 Performance 6.9.1 Latency Security (IxCryptoAcc) API 7 7.1 Whats New 7.2 Overview 7.3 IxCryptoAcc API Architecture 7.3.1 IxCryptoAcc Interfaces 7.3.2 Basic API Flow 7.3.3 Context Registration and the Cryptographic Context Database Intel XScale Core Page Page 7.3.4 Buffer and Queue Management 7.3.5 Memory Requirements 7.3.6 Dependencies 7.3.7 Other API Functionality 7.3.8 Error Handling 7.3.9 Endianness 7.3.10 Import and Export of Cryptographic Technology 7.4 IPSec Services 7.4.1 IPSec Background and Impl ementation Page 7.4.2 IPSec Packet Formats 7.4.2.1 Reference ESP Dataflow Access-Layer Components: Security (IxCryptoAcc) API 100 Document Number: 252539, Revision: 007 7.4.2.2 Reference AH Dataflow Figure 34. ESP Data Flow B2333-02 7.4.3 Hardware Acceleration for IPSec Services 7.4.4 IPSec API Call Flow Page 7.4.5 Special API Use Cases 7.4.5.1 HMAC with Key Size Greater Than 64 Bytes 7.4.5.2 Performing CCM (AES CTR-Mode Encryption and AES CBC-MAC Authentication) for IPSec Page Page 7.4.6 IPSec Assumptions, Dependencies, and Limitations 7.5 WEP Services 7.5.1 WEP Background and Implementation 7.5.2 Hardware Acceleration for WEP Services 7.5.3 WEP API Call Flow Page 7.6 SSL and TLS Protocol Usage Models 7.7 Supported Encryption and Authentication Algorithms 7.7.1 Encryption Algorithms 7.7.2 Cipher Modes 7.7.3 Authentication Algorithms Page DMA Access Driver (IxDmaAcc) API 8 8.1 Whats New 8.2 Overview 8.3 Features 8.5 Dependencies 8.6 DMA Access-Layer API 8.6.1 IxDmaAccDescriptorManager 8.7 Parameters Description 8.7.1 Source Address 8.7.2 Destination Address 8.7.3 Transfer Mode 8.7.4 Transfer Width 8.7.5 Addressing Modes 8.7.6 Transfer Length 8.7.7 Supported Modes Access-Layer Components: DMA Access Driver (IxDmaAcc) API 122 Document Number: 252539, Revision: 007 8.8 Data Flow 8.9 Control Flow 8.9.1 DMA Initialization 8.9.2 DMA Configuration and Data Transfer Page 8.10 Restrictions of the DMA Transfer 8.11 Error Handling 8.12 Little Endian Ethernet Access (IxEthAcc) API 9 9.1 Whats New 9.2 IxEthAcc Overview 9.3 Ethernet Access Layers: Architectural Overview 9.3.1 Role of the Ethernet NPE Microcode 9.3.2 Queue Manager 9.3.3 Learning/Filtering Database 9.3.4 MAC/PHY Configuration 9.4 Ethernet Access Layers: Component Features Document Number: 252539, Revision: 007 133 9.5 Data Plane The data plane is responsible for the transmission and reception of Ethernet frames. Figure 48. Ethernet Access Layers Block Diagram System Config PHY Manageme nt 9.5.1 Port Initialization 9.5.2 Ethernet Frame Transmission 9.5.2.1 Transmission Flow 9.5.2.2 Transmit Buffer Management and Priority 136 Document Number: 252539, Revision: 007 Figure 50. Ethernet Transmit Frame Data Buffer Flow 9.5.2.3 Using Chained IX_OSAL_MBUFs for Transmission / Buffer Sizing 9.5.3 Ethernet Frame Reception 9.5.3.1 Receive Flow 9.5.3.2 Receive Buffer Management and Priority Page Page 142 Document Number: 252539, Revision: 007 9.5.3.3 Additional Receive Path Information Figure 52. Ethernet Receive Plane Data Buffer Flow Frames Ethernet Incoming 9.6 Control Path Page 9.6.1 Ethernet MAC Control 9.6.1.1 MAC Duplex Settings 9.6.1.2 MII I/O 9.6.1.3 Frame Check Sequence Page 9.6.1.7 NPE Loopback 9.6.1.8 Emergency Security Port Shutdown 9.7 Initialization 9.8 Shared Data Structures Page Document Number: 252539, Revision: 007 149 Table 19. IX_OSAL_MBUF Header Definitions for the Ethernet Subsystem (Sheet 1 of 3) 150 Document Number: 252539, Revision: 007 Table 19. IX_OSAL_MBUF Header Definitions for the Ethernet Subsystem (Sheet 2 of 3) Document Number: 252539, Revision: 007 151 Table 20. IX_OSAL_MBUF Port ID Field Format Table 19. IX_OSAL_MBUF Header Definitions for the Ethernet Subsystem (Sheet 3 of 3) 9.9 Management Information Document Number: 252539, Revision: 007 153 Table 23. Managed Objects for Ethernet Receive Page Ethernet Database (IxEthDB) API 10 10.1 Overview 10.2 Whats New 10.3 IxEthDB Functional Behavior 10.3.1 MAC Address Learning and Filtering 10.3.1.1 Learning and Filtering Page 10.3.1.2 Other MAC Learning/Filtering Usage Models 10.3.1.3 Learning/Filtering General Characteristics Page 10.3.2 Frame Size Filtering 10.3.3 Source MAC Address Firewall 10.3.4 802.1Q VLAN 10.3.4.1 Background VLAN Data in Ethernet Frames 10.3.4.2 Database Records Associated With VLAN IDs 10.3.4.3 Acceptable Frame Type Filtering 10.3.4.4 Ingress Tagging and Tag Removal 10.3.4.5 Port-Based VLAN Membership Filtering 10.3.4.6 Port and VLAN-Based Egress Tagging and Tag Removal Page 10.3.4.7 Port ID Extraction 10.3.5 802.1Q User Priority / QoS Support 10.3.5.1 Priority Aware Transmission 10.3.5.2 Receive Priority Queuing 10.3.5.3 Priority to Traffic Class Mapping 10.3.6 802.3 / 802.11 Frame Conversion 10.3.6.1 Background 802.3 and 802.11 Frame Formats 10.3.6.2 How the 802.3 / 802.11 Frame Conversion Feature Works Page 10.3.6.3 802.3 / 802.11 API Details 10.3.7 Spanning Tree Protocol Port Settings 10.4 IxEthDB API 10.4.1 Initialization 10.4.2 Dependencies 10.4.3 Feature Set 10.4.4 Additional Database Features 10.4.4.1 User-Defined Field 10.4.5 Dependencies on IxEthAcc Configuration Page Ethernet PHY (IxEthMii) API 11 11.1 Whats New 11.2 Overview 11.3 Features 11.5 Dependencies Feature Control (IxFeatureCtrl) API 12 12.1 Whats New 12.2 Overview 12.3 Hardware Feature Control 12.3.1 Using the Product ID-Related Functions 12.3.2 Using the Feature Control Register Functions 12.4 Component Check by Other APIs 12.5 Software Configuration 12.6 Dependencies Page HSS-Access (IxHssAcc) API 13 13.1 Whats New 13.2 Overview 13.3 IxHssAcc API Overview 13.3.1 IxHssAcc Interfaces 13.3.2 Basic API Flow 13.3.3 HSS and HDLC Theory and Coprocessor Operation 512 KHz 1.536 MHz 2.048 MHz 4.096 MHz PeriodPeriodPj = = 13.3.4 High-Level API Call Flow 13.3.5 Dependencies 13.3.6 Key Assumptions 13.3.7 Error Handling 13.4 HSS Port Initialization Details Page 13.5 HSS Channelized Operation 13.5.1 Channelized Connect and Enable Page 13.5.2 Channelized Tx/Rx Methods 13.5.2.1 CallBack 13.5.2.2 Polled Page 13.5.3 Channelized Disconnect 13.6 HSS Packetized Operation 13.6.1 Packetized Connect and Enable Page 13.6.2 Packetized Tx Page 13.6.3 Packetized Rx Page Page 13.6.4 Packetized Disconnect 13.6.5 56-Kbps, Packetized Raw Mode 13.7 Buffer Allocation Data-Flow Overview 13.7.1 Data Flow in Packetized Service Page Page 13.7.2 Data Flow in Channelized Service Page ... Access-Layer Components: HSS-Access (IxHssAcc) API Document Number: 252539, Revision: 007 217 Figure 70. HSS Channelized Transmit Operation ... NPE-A HssChannelized Tx Operation Page NPE-Downloader (IxNpeDl) API 14 14.1 Whats New 14.2 Overview 14.3 Microcode Images 14.4 Standard Usage Example Access-Layer Components: NPE-Downloader (IxNpeDl) API Document Number: 252539, Revision: 007 221 Table 42. NPE-A Images Access-Layer Components: NPE-Downloader (IxNpeDl) API 222 Document Number: 252539, Revision: 007 Table 43. NPE-B Images Table 44. NPE-C Images (Sheet 1 of 2) 14.5 Custom Usage Example 14.6 IxNpeDl Uninitialization 14.7 Deprecated APIs NPE Message Handler (IxNpeMh) API 15 15.1 Whats New 15.2 Overview 15.3 Initializing the IxNpeMh 15.3.1 Interrupt-Driven Operation 15.3.2 Polled Operation 15.4 Uninitializing IxNpeMh 15.5 Sending Messages from an Intel XScale Core Software Client to an NPE 15.5.1 Sending an NPE Message 15.5.2 Sending an NPE Message with Response Client NPE B NPE CNPE A IxNpeMh Customer / Demo Code 15.6 Receiving Unsolicited Messages from an NPE to Client Software Client NPE B NPE CNPE A IxNpeMh Customer / Demo Code Client NPE B NPE CNPE A Customer / Demo Code Access Driver NPEs 15.7 Dependencies 15.8 Error Handling Page Parity Error Notifier (IxParityENAcc) API 16 16.1 Whats New 16.2 Introduction 16.2.1 Background 16.2.2 Parity and ECC Capabilities in the Intel IXP45X and Intel IXP46X Product Line 16.2.2.1 Network Processing Engines 16.2.2.2 Switching Coprocessor in NPE B (SWCP) 16.2.2.3 AHB Queue Manager (AQM) 16.2.2.4 DDR SDRAM Memory Controller Unit (MCU) 16.2.2.5 Expansion Bus Controller 16.2.2.6 PCI Controller 16.2.3 Interrupt Prioritization 16.3 IxParityENAcc API Details 16.3.1 Features 16.3.2 Dependencies 16.4 IxParityENAcc API Usage Scenarios 16.4.1 Summary Parity Error Notification Scenario 16.4.2 Summary Parity Error Recovery Scenario 16.4.3 Summary Parity Error Prevention Scenario 16.4.4 Parity Error Notification Detailed Scenarios Page 244 Document Number: 252539, Revision: 007 Figure 79. Data Abort followed by Unrelated Parity Error Notification B4386-01 Interrupt-1 Interrupt-2 Document Number: 252539, Revision: 007 245 Figure 81. Data Abort Caused by Parity Error B4382-01 Figure 82. Parity Error Notification Followed by Related Data Abort 246 Document Number: 252539, Revision: 007 Figure 83. Data Abort with both Related and Unrelated Parity Errors B4379-01 Performance Profiling (IxPerfProfAcc) API 17 17.1 Whats New 17.2 Overview 17.3 Intel XScale Core PMU 17.3.1 Counter Buffer Overflow 17.4 Internal Bus PMU 17.5 Idle-Cycle Counter Utilities (Xcycle) 17.6 Dependencies 17.7 Error Handling 17.8 Interrupt Handling 17.9 Threading 17.10 Using the API 17.10.1 API Usage for Intel XScale Core PMU 17.10.1.1 Event and Clock Counting Page 17.10.1.2 Time-Based Sampling Page 17.10.1.3 Event-Based Sampling Page Page 17.10.1.4 Using Intel XScale Core PMU to Determine Cache Efficiency 17.10.2 Internal Bus PMU 17.10.2.1 Using the Internal Bus PMU Utility to Monitor Read/Write Activity on the North Bus 17.10.3 Xcycle (Idlecycle Counter) Page Queue Manager (IxQMgr) API 18 18.1 Whats New 18.2 Overview 18.3 Features and Hardware Interface 18.4 IxQMgr Initialization and Uninitialization 18.5 Queue Configuration 18.6 Queue Identifiers 18.7 Configuration Values 18.8 Dispatcher 18.9 Dispatcher Modes Page AQM 18.10 Livelock Prevention AQM 18.11 Threading 18.12 Dependencies Synchronous Serial Port (IxSspAcc) API 19 19.1 Whats New 19.2 Introduction 19.3 IxSspAcc API Details 19.3.1 Features 19.3.2 Dependencies 19.4 IxSspAcc API Usage Models 19.4.1 Initialization and General Data Model 19.4.2 Interrupt Mode Page Access-Layer Components: Synchronous Serial Port (IxSspAcc) API Document Number: 252539, Revision: 007 279 Figure 93. Interrupt Scenario Rx FIFO Overrun handler Data processing 19.4.3 Polling Mode Page Page Time Sync (IxTimeSyncAcc) API 20 20.1 Whats New 20.2 Introduction 20.2.1 IEEE 1588 PTP Protocol Overview 20.2.2 IEEE 1588 Hardware Assist Block Page Page 20.2.3 IxTimeSyncAcc 20.2.4 IEEE 1588 PTP Client Application 20.3 IxTimeSyncAcc API Details 20.3.1 Features 20.3.2 Dependencies 20.3.3 Error Handling 20.4 IxTimeSyncAcc API Usage Scenarios 20.4.1 Polling for Transmit and Receive Timestamps 20.4.2 Interrupt Mode Operations 20.4.3 Polled Mode Operations Page UART-Access (IxUARTAcc) API 21 21.1 Whats New 21.2 Overview 21.3 Interface Description 21.4 UART / OS Dependencies 21.4.1 FIFO Versus Polled Mode 21.5 Dependencies Page USB Access (ixUSB) API 22 22.1 Whats New 22.2 Overview 22.3 USB Controller Background 22.3.1 Packet Formats Connection Endpoint configuration Address assignment Toke n Data 22.3.2 Transaction Formats Page Page 22.4 ixUSB API Interfaces 22.4.1 ixUSB Setup Requests 22.4.1.1 Configuration 22.4.1.2 Frame Synchronization 22.4.2 ixUSB Send and Receive Requests 22.4.3 ixUSB Endpoint Stall Feature 22.4.4 ixUSB Error Handling Page 22.5 USB Data Flow 22.6 USB Dependencies Codelets 23 23.1 Whats New 23.2 Overview 23.3 ATM Codelet (IxAtmCodelet) 23.4 Crypto Access Codelet (IxCryptoAccCodelet) 23.5 DMA Access Codelet (IxDmaAccCodelet) 23.6 Ethernet AAL-5 Codelet (IxEthAal5App) 23.7 Ethernet Access Codelet (IxEthAccCodelet) 23.8 HSS Access Codelet (IxHssAccCodelet) 23.9 Parity Error Notifier Codelet (IxParityENAccCodelet) 23.10 Performance Profiling Codelet (IxPerfProfAccCodelet) 23.11 Time Sync Codelet (IxTimeSyncAccCodelet) 23.12 USB RNDIS Codelet (IxUSBRNDIS) Operating System Abstraction Layer (OSAL) 24 24.1 Whats New 24.2 Overview Operating System Abstraction Layer (OSAL) Translation 24.3 OS-Independent Core Module 24.4 OS-Dependent Module 24.4.1 Backward Compatibility Module 24.4.2 Buffer Translation Module 24.5 OSAL Library Structure Page Page 24.6 OSAL Modules and Related Interfaces 24.6.1 Core Module Page Page 24.6.2 Buffer Management Module 24.6.3 I/O Memory and Endianness Support Module Page 24.7 Supporting a New OS 24.8 Supporting New Platforms Page ADSL Driver 25 25.1 Whats New 25.2 Device Support 25.3 ADSL Driver Overview 25.4 ADSL API 25.5 ADSL Line Open/Close Overview Page 25.6 Limitations and Constraints I2C Driver (IxI2cDrv) 26 26.1 Whats New 26.2 Introduction 26.3 I2C Driver API Details 26.3.1 Features 26.3.2 Dependencies 26.3.3 Error Handling 26.3.3.1 Arbitration Loss Error 26.3.3.2 Bus Error 26.4 I2C Driver API Usage Models 26.4.1 Initialization and General Data Model Page I2C Driver (IxI2cDrv) 336 Document Number: 252539, Revision: 007 26.4.2 Example Sequence Flows for Slave Mode Figure 110. Sequence Flow Diagram for Slave Receive / General Call in Interrupt Mode B4375-01 Page Page 26.4.3 I2C Using GPIO Versus Dedicated I2C Hardware Page Endianness in Intel IXP400 Software 27 27.1 Overview 27.2 The Basics of Endianness 27.2.1 The Nature of Endianness: Hardware or Software? 0 0 Byte 0 Byte 1 Byte 2 Byte 3 Byte 3 Byte 2 Byte 1 Byte 0 27.3 Software Considerations and Implications 27.3.1 Coding Pitfalls Little-Endian/Big-Endian 27.3.1.1 Casting a Pointer Between Types of Different Sizes 27.3.1.2 Network Stacks and Protocols 27.3.1.3 Shared Data Example: LE Re-Ordering Data for BE Network Traffic 27.3.2 Best Practices in Coding of Endian-Independence 27.3.3 Macro Examples: Endian Conversion 27.3.3.1 Macro Source Code Endianness in Intel IXP400 Software Document Number: 252539, Revision: 007 347 27.4.1 Supporting Little-Endian Mode 27.4.2 Reasons for Choosing a Particular LE Coherency Mode 27.4.3 Silicon Endianness Controls 27.4.3.1 Hardware Switches Endianness in Intel IXP400 Software 350 Document Number: 252539, Revision: 007 27.4.3.2 Intel XScale Core Endianness Mode 27.4.3.3 Little-Endian Data Coherence Enable/Disable 27.4.3.4 MMU P-Attribute Bit 27.4.3.5 PCI Bus Swap 27.4.3.6 Summary of Silicon Controls 27.4.4 Silicon Versions 27.5 Little-Endian Strategy in Intel IXP400 Software and Associated BSPs 27.5.1 APB Peripherals 27.5.2 AHB Memory-Mapped Registers 27.5.3 Intel IXP400 Software Core Components 27.5.3.1 Queue Manager IxQMgr 27.5.3.2 NPE Downloader IxNpeDl 27.5.3.3 NPE Message Handler IxNpeMh 27.5.3.4 Ethernet Access Component IxEthAcc 27.5.3.5 ATM and HSS 27.5.4 PCI 27.5.5 Intel IXP400 Software OS Abstraction 27.5.6 VxWorks* Considerations Page 27.5.7 Software Versions