sprufp2 tms320c6000 network developer\'s kit(NDK)support package Ethernet driver design guide

TMS320C6000 Network Developer's Kit (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 with TI's standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary 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 are responsible 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 (800) 477-8924. 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 NDK Operating 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. Ethernet Driver Architecture Architecture Overview 1-5 For the most part, the mini-driver invokes CSL APIs for setup, Tx, and interrupt service operations. The CSL layer, however, can also invoke the mini-driver layer. The CSL layer can invoke the mini-driver registered callback functions (set up during EMAC_open) for updating statistics and reporting errors. On receiving a packet, it can hand over the packet to be passed up the stack or for memory allocation/free of buffers in BDs. This layer is OS agnostic, since it uses the NDK OS AL for all memory and interrupt management operations. However, this layer is device- dependent since the EMAC peripheral setup requires knowledge of the capabilities of EMAC on this platform/device and will have to be customized for each platform and for application needs. So, this layer needs to be ported and customized from one platform to another. 1.2.3 Generic EMAC/MDIO Chip Support Library This layer enables the generic driver architecture by doing the following: ❏ EMAC APIs. It defines the data structures and interfaces (APIs) required to configure and use EMAC for transmit and receive operations. ❏ MDIO and SGMII APIs. It exposes APIs for managing the PHY- related (physical layer) configuration through the MDIO and SGMII (if the PHY is capable of gigabit speed) modules. ❏ BD logic. It implements the basic logic for CPPI Buffer Descriptor management (setup, enqueuing, and dequeuing operations). ❏ ISR logic. It contains the central logic for interrupt service routines. However, it uses the mini-driver's registered callback functions to report packet reception, statistics, errors, and obtaining or freeing a buffer for filling up a BD. This layer is largely generic and doesn't vary much from platform to platform unless the EMAC capabilities change a whole lot. For example, the CSL for an EMAC peripheral connecting to a PHY switch would be very different from an EMAC that connects to a single PHY port. This layer is easily portable to different devices with similar capabilities. Flow Charts 1-6 1.3 Flow Charts The transmission path for Ethernet packets is as follows: User Application send/sendto socket API NIMUSendPacket NDK Stack Processing (L4 – TCP/UDP/RAW and IP) Allocate Packet, Copy Data Buf f er; Add headers and if needed f ragment packets Dev ice Driv er’s registered “send” callback f unction EmacSend (nimu_eth.c) Is link up and Transmitter ready ? (TxFree is 1?) HwPktTxNext Yes No