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
Intended Audience
Introduction1
Versions Supported by this Document
Hardware Supported by this Release
How to Use this Document
About the Processors
Chapters 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 Support
Development Tools
Ixposal Include Src Ixp400xscalesw
Release Directory Structure
\---include +---npeMh
Threading and Locking Policy
Polled and Interrupt Operation
Statistics and MIBs
Global Dependencies
Global Dependency Chart
This page is intentionally left blank
Buffer Management
What’s New
Overview
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
Ixreserved
Ixmbuf Structure
Internal Ixmbuf Field Format Sheet 1
Ixnext Ixosalmbufnextbufferinpktptr
Field / Macro Purpose Used by Access-Layer?
Internal Ixmbuf Field Format Sheet 2
Ixmbuf Field Details Sheet 1
Mapping to OS Native Buffer Types
VxWorks* Mblk Buffer
Ixmbuf 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 Summary
Buffer 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 Service
ATM 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 Processing
Receive Based on a Threshold Level
Rx Using a Threshold Level
Receive Disconnect
RX Using a Polling Mechanism
Buffer Contents
Buffer Management
Buffer Allocation
Field Description
Ixpbuf Fields Required for Transmission
Ixpbuf Fields of Available Buffers for Reception
Ixpbuf Fields Modified During Reception Sheet 1
Buffer-Chaining Constraints
Error Handling
API-Usage Errors
Buffer-Size Constraints
Real-Time Errors
Real-Time Errors
Cause Consequences and Side Effects Corrective Action
Access-Layer Components ATM Manager IxAtmm API
IxAtmm Component Features
IxAtmm 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
Memory Requirements
Error Handling
Dependencies
Management Interfaces
Performance
IxAtmSch Component Features
Access-Layer Components ATM Transmit Scheduler IxAtmSch
Access-Layer Components ATM Transmit Scheduler IxAtmSch API
Supported Traffic Types
Traffic Type Supported Num VCs
Connection Admission Control CAC Function
Schedule Table
Scheduling and Traffic Shaping
Schedule Service Model
Minimum Cells Value minCellsToSchedule
Maximum Cells Value maxCells
Timing and Idle Cells
Per VC Data Per Port Data Total
Code Size
Data Memory
IxAtmSch Data Memory Usage
Latency
Access-Layer Components Security IxCryptoAcc API
Access-Layer Components Security IxCryptoAcc API
IxCryptoAcc API Architecture
IxCryptoAcc 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
Structure Size in Bytes Total Size in Bytes
Buffer and Queue Management
Memory Requirements
IxCryptoAcc Data Memory Usage Sheet 1
IxCryptoAcc Data Memory Usage Sheet 2
Dependencies
IxCryptoAccHashKeyGenerate
Other API Functionality
IPSec Background and Implementation
IPSec Services
Endianness
Import and Export of Cryptographic Technology
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 Limitations
WEP Background and Implementation
WEP Frame with Request Parameters
Hardware Acceleration for WEP Services
NPE Microcode Images
WEP API Call Flow
IxCryptoAccNpeWepPerform
IxCryptoAccXscaleWepPerform
WEP Perform API Call Flow
Encryption/Decryption
Authentication
Combined Mode Operations
SSL and TLS Protocol Usage Models
Cipher Key Sizes Parity Bit Actual Key Size
Supported Encryption and Authentication Algorithms
Encryption Algorithms
Supported Encryption Algorithms
Cipher Block Chaining CBC
Counter Mode CTR
Cipher Modes
Electronic Code Book ECB
Authentication Algorithms
Supported Authentication Algorithms
Authentication Algorithm Data Block Size Bits Key Size Bits
114 Document Number 252539, Revision
Access-Layer Components DMA Access Driver IxDmaAcc API
Features
Assumptions
Access-Layer Components DMA Access Driver IxDmaAcc API
DMA Access-Layer API
IxDmaAcc Component Overview
IxDmaAccDescriptorManager
Parameters Description
Transfer Width
Transfer Mode
Source Address
Destination Address
Transfer Length
Addressing Modes
Transfer Mode
Supported Modes
Increment
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 API
Role of the Ethernet NPE Microcode
4 MAC/PHY Configuration
Queue Manager
Learning/Filtering Database
Ethernet Access Layers Component Features
Data Plane
Ethernet Access Layers Block Diagram
Port Initialization
Ethernet Frame Transmission
Transmission Flow
Transmit Buffer Management and Priority
TxEnetDone
Ethernet Transmit Frame Data Buffer Flow
Using Chained IXOSALMBUFs for Transmission / Buffer Sizing
Ethernet Frame Reception
Tx Fifo Priority
Ethernet Receive Frame API Overview
Receive Flow
Receive Buffer Management and Priority
Buffer Sizing
Supplying Buffers
Codelet or client application
Programmer’s Guide
Rx Fifo Priority QoS Mode
Freeing Buffers
Recycling Buffers
No Receive Polling
Additional Receive Path Information
Control Path
Data-Plane Endianness
Maximum Ethernet Frame Size
IxEthAcc and Secondary Components
Frame Check Sequence
MAC Duplex Settings
Ethernet MAC Control
MII I/O
1.6 802.3x Flow Control
Promiscuous Mode
Non-Promiscuous Mode
MAC Filtering
Emergency Security Port Shutdown
Initialization
Shared Data Structures
NPE Loopback
Ixpneflags Field Format
Ixosalmbuf Structure Format
Queue Field Description Eth
150 Document Number 252539, Revision
Ixosalmbuf Port ID Field Format
Field Bit Values
Management Information
Ixosalmbuf Port ID Field Values
Ixpneflags.linkprot Field 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 Filtering
Learning and Filtering
Node
Learning/Filtering General Characteristics
Other MAC Learning/Filtering Usage Models
Port Definitions
Port Dependency Map
Provisioning Static and Dynamic Entries
Aging
Database Maintenance
Frame Size Filtering
Record Management
Source MAC Address Firewall
Filtering Example Based Upon Maximum Frame Size
MAC Address Block/Admission
Invalid MAC Address Filtering
10.3.4 802.1Q Vlan
Background Vlan Data in Ethernet Frames
Untagged MAC Frame Format
Vlan Tagged MAC Frame Format
Database Records Associated With Vlan IDs
Acceptable Frame Type Filtering
Vlan 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 Extraction
Priority Aware Transmission
QoS on Receive for 802.1Q Tagged Frames
Receive Priority Queuing
QoS on Receive for Untagged Frames
Priority to Traffic Class Mapping
IEEE802.11 Frame Format
Default Priority to Traffic Class Mapping
10.3.6 802.3 / 802.11 Frame Conversion
Background 802.3 and 802.11 Frame Formats
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 Rules
Transmit Path
Frame Type
10.3.6.3 802.3 / 802.11 API Details
11 to 802.3 Header Conversion Rules
Input 802.11 Frame Values Output 802.3 Frame Field Values
Spanning Tree Protocol Port Settings
IxEthDB API
Initialization
User-Defined Field
Feature Set
Additional Database Features
IxEthDB Feature Set
FCS Appending
Dependencies on IxEthAcc Configuration
Database Clear
Promiscuous-Mode Requirement
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
Bits Description
Using the Product ID-Related Functions
Access-Layer Components Feature Control IxFeatureCtrl API
Product ID Values
Feature Control Register Values Sheet 1
Using the Feature Control Register Functions
Software Configuration
Feature Control Register Values Sheet 2
Component 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 Overview
IxHssAcc 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 Error
HSS Tx Freq Pj Max ns Cj Max ns Aj Max ns
Actual Frame Length µs
Jitter Definitions
HSS Frame Output Characterization
Jitter Type Jitter Definition
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 Operation
IxHssAccChanConnect
200 Document Number 252539, Revision
Channelized Connect
Channelized Tx/Rx Methods
Polled
CallBack
Channelized Transmit and Receive
IxHssAccPktPortConnect
Packetized Connect and Enable
HSS Packetized Operation
Channelized Disconnect
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
Packetized Disconnect
13.6.5 56-Kbps, Packetized Raw Mode
Data Flow in Packetized Service
Buffer Allocation Data-Flow Overview
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 Images
Loading NPE Microcode from a File Versus Loaded from Memory
NPE Image Compatibility
Access-Layer Components NPE-Downloader IxNpeDl API
Standard Usage Example
NPE Microcode Library Customization
Image Name Description
NPE-A Images
NPE-C Images Sheet 1
NPE-B Images
Custom Usage Example
IxNpeDl Uninitialization
NPE-C Images Sheet 2
Deprecated APIs
Access-Layer Components NPE Message Handler IxNpeMh API
Polled Operation
Access-Layer Components NPE Message Handler IxNpeMh API
Initializing the IxNpeMh
Interrupt-Driven Operation
Sending an NPE Message
Uninitializing IxNpeMh
IxNpeMh
Sending an NPE Message with Response
Client
Customer / Demo Code
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
Introduction
Background
Scrubbing/Memory Scrub
Network Processing Engines
Expansion Bus Controller
Switching Coprocessor in NPE B Swcp
AHB Queue Manager AQM
DDR Sdram Memory Controller Unit MCU
Secondary Effects of Parity Interrupts
Parity Error Interrupts
Interrupt Bit Default Priority Software
Interrupt Prioritization
Features
Feature Hardware Component Software Support Recoverable
IxParityENAcc 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
Attribute Description Values
Configuration Values
AQM Configuration Attributes
Dispatcher
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 Models
Initialization 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 Overview
Synchronization 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
Additional Hardware Information
IxTimeSyncAcc API Details
IxTimeSyncAcc
Ieee 1588 PTP Client Application
Document Number 252539, Revision 289
Interrupt Mode Operations
IxTimeSyncAcc API Usage Scenarios
Polling 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 API
Uart / OS Dependencies
Uart Services Models
296 Document Number 252539, Revision
USB Controller Background
Access-Layer Components USB Access ixUSB API
SOF Token Packet Format
Access-Layer Components USB Access ixUSB API
IN, OUT, and Setup Token Packet Format
Packet Formats
Bits 023 Bytes
Transaction Formats
Data Packet Format
Handshake Packet Format
Action Token Packet Data Packet
Bulk Transaction Formats
Isochronous Transaction Formats
Action Token Packet Data Packet Handshake Packet
Interrupt Transaction Formats
Control Write Setup
Control Transaction Formats, Set-Up Stage
Control Transaction Formats
IxUSB Setup Requests
API interfaces Available for Access Layer
IxUSB 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 Requests
Frame Synchronization
Stall on OUT Transactions
IxUSB Error Handling
Error due to unknown reasons
Detailed Error Codes
USB Dependencies
USB Data Flow
Codelets
ATM Codelet IxAtmCodelet
Codelets
Ethernet AAL-5 Codelet IxEthAal5App
Crypto Access Codelet IxCryptoAccCodelet
DMA Access Codelet IxDmaAccCodelet
Ethernet Access Codelet IxEthAccCodelet
Parity Error Notifier Codelet IxParityENAccCodelet
HSS Access Codelet IxHssAccCodelet
Performance Profiling Codelet IxPerfProfAccCodelet
Time Sync Codelet IxTimeSyncAccCodelet
USB Rndis Codelet IxUSBRNDIS
Operating System Abstraction Layer Osal
Osal Architecture
Operating System Abstraction Layer Osal
Buffer Management Module
OS-Independent Core Module
OS-Dependent Module
Core Module
Osal Library Structure
Backward Compatibility Module
Buffer 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 Module
Osal 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 Support
Adsl 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
Initialization
Bus Error
Master-Interrupt Mode
26.4 I2C Driver API Usage Models
I2C Driver IxI2cDrv Slave-Interrupt Mode
Slave-Polling Mode
Support 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 Endianness
Endianness in Intel IXP400 Software
Nature of Endianness Hardware or Software?
Endianness When Memory is Shared
Software Considerations and Implications
Coding Pitfalls Little-Endian/Big-Endian
Casting a Pointer Between Types of Different Sizes
Here is what the macro ntohl looks like in actual code
Network Stacks and Protocols
Avoid
Best Practices in Coding of Endian-Independence
Macro Examples Endian Conversion
Macro Source Code
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
Forcebyteswap Bit
Little-Endian Data Coherence Enable/Disable
MMU P-Attribute Bit
Byteswapen Bit
Endian Hardware Summary
Silicon Versions
PCI Bus Swap
Summary of Silicon Controls
Part Number Brief Description
IXP46X network processors A-0 stepping
APB Peripherals
April 2005
Ethernet Access Component IxEthAcc
NPE Downloader IxNpeDl
NPE 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 Function
Intel IXP400 Software IxEthAcc and IxEthDB Summary
27.5.4 PCI
Intel IXP400 Software OS Abstraction
ATM and HSS
#defines
VxWorks* Considerations
Intel IXP400 Software Macros
Endian Conversion Macros
VxWorks* Data Coherent Swap Code
Software Versions
Intel IXP400 Software Versions
Intel IXP400 Software Version Little-Endian Support Yes/No