Texas Instruments TMS320C6000 DSP Guide

TMS320C6000NetworkDeveloper'sKit
(NDK) Support Package Ethernet
Driver Design Guide
Literature Number: SPRUFP2
January 2009

IMPORTANT NOTICE
Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications,
enhancements, improvements, and other changes to its products and services at any time and to discontinue any
product or service without notice. Customers should obtain the latest relevant information before placing orders
and should verify that such information is current and complete. All products are sold subject to TI's terms and
conditions of sale supplied at the time of order acknowledgment.
TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance
withTI'sstandardwarranty.TestingandotherqualitycontroltechniquesareusedtotheextentTIdeemsnecessary
to support this warranty. Except where mandated by government requirements, testing of all parameters of each
product is not necessarily performed.
TI assumes no liability for applications assistance or customer product design. Customers areresponsible for their
products and applications using TI components. To minimize the risks associated with customer products and
applications, customers should provide adequate design and operating safeguards.
TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right,
copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process
in which TI products or services are used. Information published by TI regarding third-party products or services
does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use
of such information may require a license from a third party under the patents or other intellectual property of the
third party, or a license from TI under the patents or other intellectual property of TI.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration
and is accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this infor-
mation with alteration is an unfair and deceptive business practice. TI is not responsible or liable for such altered
documentation.
Resale of TI products or services with statements different from or beyond the parameters stated by TI for that
product or service voids all express and any implied warranties for the associated TI product or service and is an
unfair and deceptive business practice. TI is not responsible or liable for any such statements.
Following are URLs where you can obtain information on other Texas Instruments products and application
solutions:
Mailing Address: Texas Instruments
Post Office Box 655303 Dallas, Texas 75265
Copyright © 2009, Texas Instruments Incorporated
Products Applications
Amplifiers amplifier.ti.com Audio www.ti.com/audio
Data Converters dataconverter.ti.com Automotive www.ti.com/automotive
DSP dsp.ti.com Broadband www.ti.com/broadband
Interface interface.ti.com Digital Control www.ti.com/digitalcontrol
Logic logic.ti.com Military www.ti.com/military
Power Mgmt power.ti.com Optical Networking www.ti.com/opticalnetwork
Microcontrollers microcontroller.ti.com Security www.ti.com/security
Low Power Wireless www.ti.com/lpw Telephony www.ti.com/telephony
Video & Imaging www.ti.com/video
Wireless www.ti.com/wireless

iii
This is a draft version printed from file: pref.fm on 1/5/09
Preface
About This Guide
This document describes the design of the Ethernet driver architecture
introduced in NDK 2.0. This design differs from that in previous versions
of NDK. All Ethernet drivers packaged as a part of the Network
Developer's Kit (NDK) Support Package in NDK 2.0 follow the generic
architecture described in this document.
Important Note:
❏This document covers only the Ethernet driver architecture. The
serial driver is no longer supported as of NDK 2.0. For serial driver
information, see documentation from earlier releases of the NDK.
❏The setup and installation steps for each NDK Support Package
(NSP) are provided in the Release Notes provided with that NSP.
Intended Audience
This document is intended for writers of Ethernet mini-drivers. This
document assumes you have knowledge of Ethernet concepts.
Related Documents The following books describe the TMS320C6x devices and related
support tools. To obtain a copy of any of these TI documents, call the
Texas Instruments Literature Response Center at [phone]. When
ordering, please identify the book by its title and literature number. Many
of these documents can be found on the Internet at http://www.ti.com.
❏SPRU189 - TMS320C6000 CPU and Instruction Set Reference
Guide. Describes the CPU architecture, pipeline, instruction set, and
interrupts for the TMS320C6000 DSPs.
❏SPRU190 - TMS320C6000 DSP Peripherals Overview Reference
Guide. Provides an overview and briefly describes peripherals
available on the TMS320C6000 family of DSPs.
❏SPRU197 - TMS320C6000 Technical Brief. Provides an introduction
to the TMS320C62x and TMS320C67x digital signal processors
(DSPs) of the TMS320C6000 DSP family. Describes the CPU
architecture, peripherals, development tools, and third-party support
for the C62x and C67x DSPs.

iv
Notational Conventions
❏SPRU198 - TMS320C6000 Programmer's Guide. Reference for
programming the TMS320C6000 digital signal processors (DSPs).
Before you use this manual, you should install your code generation
and debugging tools. Includes a brief description of the C6000 DSP
architecture and code development flow, includes C code examples
and discusses optimization methods for the C code, describes the
structure of assembly code and includes examples and discusses
optimizations for the assembly code, and describes programming
considerations for the C64x DSP.
❏SPRU509 - Code Composer Studio Development Tools v3.3 Getting
Started Guide introduces some of the basic features and
functionalities in Code Composer Studio to enable you to create and
build simple projects.
❏SPRU523 - TMS320C6000 Network Developer's Kit (NDK) Software
User's Guide. Describes how to use the NDK libraries, how to
develop networking applications on TMS320C6000 platforms, and
ways to tune the NDK to fit a particular software environment.
❏SPRU524 - TMS320C6000 Network Developer's Kit (NDK) Software
Programmer's Reference Guide. Describes the various API functions
provided by the stack libraries, including the low level hardware APIs.
Notational Conventions
This document uses the following conventions:
❏Program listings, program examples, and interactive displays are
shown in a mono-spaced font. Examples use bold for emphasis,
and interactive displays use bold to distinguish commands that you
enter from items that the system displays (such as prompts,
command output, error messages, etc.).
❏Square brackets ( [ and ] ) identify an optional parameter. If you use
an optional parameter, you specify the information within the
brackets. Unless the square brackets are in a bold typeface, do not
enter the brackets themselves.
Trademarks The Texas Instruments logo and Texas Instruments are registered
trademarks of Texas Instruments. Trademarks of Texas Instruments
include: TI, Code Composer, Code Composer Studio, DSP/BIOS,
TMS320, TMS320C6000, TMS320C64x, TMS320DM644x, and
TMS320C64x+.
All other brand, product names, and service names are trademarks or
registered trademarks of their respective companies or organizations.
January 5, 2009

v
This is a draft version printed from file: ndk_spTOC.fm on 1/5/09
Contents
1 Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1
This chapter provides an overview of the terminology and components involved in the Network De-
veloper's Kit Support Package (NSP) Ethernet driver. It also describes the architecture of such
drivers.
1.1 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2
1.2 Ethernet Driver Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
1.2.1 NIMU-Specific Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4
1.2.2 Ethernet Mini-Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4
1.2.3 Generic EMAC/MDIO Chip Support Library. . . . . . . . . . . . . . . . . . . . . . . . . .1-5
1.3 Flow Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-6
1.4 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-8
1.4.1 Network Control (NETCTRL) Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-8
1.4.2 Stack Event (STKEVENT) Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-8
1.4.3 Packet Buffer (PBM) Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-8
1.4.4 NDK Interrupt Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9
1.4.5 Data Alignment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9
1.5 API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-10
2 NIMU Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1
This chapter describes Network Interface Management Unit (NIMU) layer API.
2.1 Overview of the NIMU Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2
2.2 NIMU APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2
3 Ethernet Mini-Driver Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1
This chapter describes Ethernet mini-driver layer interface.
3.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
3.2 Data Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
3.3 Ethernet Mini-Driver APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
3.3.1 HwPktInit — Initialize Packet Driver Environment . . . . . . . . . . . . . . . . . . . . .3-5
3.3.2 HwPktOpen — Open Ethernet Device Instance. . . . . . . . . . . . . . . . . . . . . . .3-5
3.3.3 HwPktClose — Close Ethernet Device and Disable Interrupts . . . . . . . . . . .3-5
3.3.4 HwPktSetRx — Configure the Ethernet Receive Filter Settings . . . . . . . . . .3-6
3.3.5 HwPktIoctl — Execute Driver-Specific IOCTL Commands . . . . . . . . . . . . . .3-6
3.3.6 HwPktTxNext — Transmit Next Buffer in the Transmit Queue . . . . . . . . . . .3-6
3.3.7 _HwPktPoll — Mini-Driver Polling Function . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
3.4 Configuration Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7

Contents
vi
4 Generic EMAC/MDIO CSL Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
This chapter describes the EMAC/MDIO CSL layer interface.
4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
4.2 CSL Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
4.3 EMAC APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
4.4 Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
4.4.1 pfcbGetPacket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
4.4.2 pfcbFreePacket. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
4.4.3 pfcbRxPacket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
4.4.4 pfcbStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
4.4.5 pfcbStatistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

1-1
Chapter 1
Architecture Overview
This chapter provides an overview of the terminology and components
involved in the Network Developer's Kit Support Package (NSP) Ethernet
driver. It also describes the architecture of such drivers.
1.1 Acronyms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2
1.2 Ethernet Driver Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
1.3 Flow Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–6
1.4 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–8
1.5 API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–10
Topic Page

Acronyms
1-2
1.1 Acronyms
The following acronyms are used in this document:
Table 1–1 Acronyms
Acronym Description
API Application Programming Interface
BD Buffer Descriptor
CSL Chip Support Library
DSP Digital Signal Processor
EMAC Ethernet Medium Access Protocol
LL Low Level Packet Driver
MDIO Management Data Input/Output Interface
NDK Network Developer's Kit
NIMU Network Interface Management Unit
NSP NDK Support Package
OS AL Operating Systems Abstraction Layer
Rx Receive Operation
SGMII Serial Gigabit Media Independent Interface
Tx Transmit Operation

Ethernet Driver Architecture
Architecture Overview 1-3
1.2 Ethernet Driver Architecture
The following diagram shows the architecture of the Ethernet driver
design in the NDK 2.0 Support Package (NSP).
This new NSP Ethernet driver architecture consists of the following
components:
❏NIMU-specific layer, which acts as the interface between the NDK
stack and the Ethernet driver. See Section 1.2.1.
❏Ethernet mini-driver, which manages the EMAC configuration
using the CSL. Also manages DSP interrupts and memory allocation
for packet buffers in buffer descriptors using the NDKOperating Systems
Abstraction Layer (OS AL). See Section 1.2.2.
❏Generic EMAC/MDIO Chip Support Library (CSL), which contains
the generic APIs and data structures needed to control and configure
EMAC/MDIO peripherals. Also manages buffer descriptors and
interrupt service routines. See Section 1.2.3.
NDK
NSP Ethernet
Driver
Hardware
Software
NDK Core Stack
NIMU NDK Core Layer
NIMU-specific layer
Ethernet PHY(s)
Ethernet mini-driver
Generic EMAC/MDIO Chip Support
Library (CSL)

Ethernet Driver Architecture
1-4
The NIMU-specific layer in previous versions of the NDK was generic
enough to be ported to different platforms with ease. However, the mini-
driver was not easily portable and had to be rewritten from scratch every
time it had to be ported to a new platform. This led to different flavors of
the Ethernet device drivers for different platforms—thus increasing the
development, maintenance, and debugging effort.
To overcome the limitations of this architecture, the architecture of
Ethernet drivers in the NSPs have been reorganized to optimize for a
better development and debugging experience. The Generic
EMAC/MDIO Chip Support Library (CSL) component is new; it has been
split apart from the Ethernet mini-driver component to better isolate
portions that commonly require changes when porting.
1.2.1 NIMU-Specific Layer
The Network Interface Management Unit (NIMU) specific layer acts as
the interface between the Ethernet driver and the NDK core stack. It
provides an implementation for the APIs defined by the NIMU
specification for this EMAC device. These APIs let the NDK core stack
control and configure the EMAC device at runtime and transmit packets.
They also enable the driver to hand any received packets back to the
stack.
This layer is fairly generic and doesn't change between different
platforms.
This layer's functionality and role are the same as in versions of NDK
prior to v2.0.
1.2.2 Ethernet Mini-Driver
This layer is responsible for setting up parameters for EMAC and MDIO
configuration according to system needs. It uses APIs and data
structures exported by the underlying Chip Support Library (CSL) layer.
It is also responsible for setting up EMAC interrupts into the DSP using
data structures and APIs exposed by the "Interrupt Manager Wrapper" in
the NDK OS AL.
This layer acts as the sole memory manager in the Ethernet driver. That
is, it handles all memory allocations, initializations, and frees of packet
buffers for use in the buffer descriptors (BDs) in the Transmit (Tx) and
Receive (Tx) paths. For memory management, it again uses the data
structures and APIs defined by the NDK OS AL.