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