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
