Texas TMS320C6000 User manual

TMS320C6000 TCP/IP
Network Developer’s Kit (NDK)
Programmer’s Reference Guide
Literature Number: SPRU524A
October 2001
Printed on Recycled Paper

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 that 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 information 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.
Mailing Address:
Texas Instruments
Post Office Box 655303
Dallas, Texas 75265
Copyright 2001, Texas Instruments Incorporated

iii
Read This First
Preface
Read This First
About This Manual
This programmer’s guide is intended to aid the development of network ap-
plications and describes the various API functions provided by the stack li-
braries. It will be the central reference document used when programming the
stack. Users should first refer to the TMS320C6000 TCP/IP Network Develop-
er’s Kit (NDK) User’s Guide (SPRU523) to familiarize themselves with the
stack libraries and in using the stack with DSP/BIOSand Code Composer
Studio.
How to Use This Manual
This document contains the following chapters:
-Chapter 1 – Introduction, summarizes the various API sets described in
the NDK documentation.
-Chapter 2 – Operating System Abstraction API,describes the API used
by the adaptation layer to access the operating system.
-Chapter 3 – Sockets and Stream IO API,describes the file and sockets
API functions.
-Chapter 4 – Initialization and Configuration, describes the TCP/IP
stack initialization and configuration, including the Configuration Manager
API and the Network Control module.
-Chapter 5 – Network Tools LIbrary Support Functions, describes the
network support functions contained in the NETTOOLS library.
-Chapter 6 – Network Tools Library Services, describes the network
servers and services contained in the NETTOOLS library.
-Appendix A – Internal Stack Functions, contains a partial list of internal
stack functions provided to aid in the comprehension of kernel oriented
calls.

Related Documentation From Texas Instruments
iv
-Appendix B –Network Address Translation, describes the optional
Network Address Translation component, how to set up virtual networks,
and protocol proxies.
-Appendix C –Point to Point Protocol, describes the operation of the
PPP and PPPoE support API included in the TCP/IP stack, and how to in-
terface a serial device.
-Appendix D –Hardware Abstraction Layer (HAL), describes the opera-
tion of the HAL, and the HAL API functions.
-Appendix E–Web Programming with the HTTP Server, describes how
to get information from an embedded network device through the web
server.
Related Documentation From Texas Instruments
The following reference is provided for further information:
TMS320C6000 TCP/IP Network Developer’s Kit (NDK) User’s Guide
(literature number SPRU523)
TMS320C6000 TCP/IP Network Developer’s Kit (NDK) Porting Guide
(literature number SPRU030)
TMS320C6000 TCP/IP Network Developer’s Kit (NDK) Technical Data
Quick Reference Guide (literature number SPRU568)
Text Conventions
The following typographical conventions are used in this specification:
-Text inside back-quotes (‘‘) represents pseudo-code
-Program source code, function and macro names, parameters, and com-
mand line commands are shown in a mono-spaced font.
Trademarks
TMS320C6000, Code composer Studio, and DSP/BIOS are trademarks of
Texas Instruments.
Text Conventions

Contents
v
Contents
1 Introduction 1-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1 This Document 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Additional Documentation 1-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Operating System Abstraction API 2-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1 Operating System Configuration 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Task Support 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Semaphore Support 2-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Memory Allocation Support 2-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Print and Debug Support 2-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6 File I/O Support for Embedded Systems 2-17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3 Sockets and Stream IO API 3-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1 File Descriptor Environment 3-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 File Descriptor Programming Interface 3-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Sockets Programming Interfaces 3-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Full Duplex Pipes Programming Interface 3-34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4 Initialization and Configuration 4-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1 Configuration Overview 4-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Configuration Manager 4-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 Network Control Initialization Procedure (NETCTRL) 4-19. . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Configuration Specification 4-23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 Network Tools Library Support Functions 5-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1 Generic Support Calls 5-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 DNS Support Calls 5-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3 TFTP Support Calls 5-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6 Network Tools Library Services 6-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1 Service Calling Conventions 6-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Telnet Server Service 6-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 DHCP Server Service 6-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 DHCP Client Support 6-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5 HTTP Server Support 6-14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6 DNS Server Service 6-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.7 Network Address Translation (NAT) Service 6-18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents
vi
A Internal Stack Functions A-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.1 Overview A-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.2 Stack Executive (Exec) A-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.3 Packet (Pkt) Object A-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.4 Packet Fragment (Frag) Object A-14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.5 Link Layer Address (LLA) Object A-20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.6 Link Layer Information (LLI) Object A-22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.7 Interface (IF) Object A-24. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.8 Ether Object A-28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.9 Binding Object A-32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.10 Timer Object A-34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.11 Route Object A-36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.12 Route Control Object A-46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.13 Configuring the Stack A-50. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.14 Network Address Translation A-57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A.15 Obtaining Stack Statistics A-59. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B Network Address Translation B-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B.1 NAT Operation B-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B.2 NAT Port Mapping B-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B.3 NAT Proxy Filters B-20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C Point to Point Protocol C-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.1 Low-Level PPP Support C-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.2 Serial HDLC Client and Server Support C-14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3 PPPoE Client and Server Support C-20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4 Creating PPP Sever User Accounts C-25. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D Hardware Abstraction Layer (HAL) D-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D.1 Overview D-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D.2 Low-Level Timer Driver (llTimer) D-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D.3 Low-Level Packet Driver (llPacket) D-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D.4 Low-Level Serial Port Driver (llSerial) D-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E Web Programming with the HTTP Server E-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.1 Adding WEB Content E-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.2 Writing CGI Functions E-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.3 CGI Function Example E-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.4 HTTP Sever Exported Functions E-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Figures
vii
Contents
Figures
A–1 Packet and Packet Fragment Objects A-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A–2 FRAG Object Properties A-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B–1 Basic Home Network Configuration B-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B–2 Public Servers on the Home Network B-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C–1 Standard PPP Frame Over Serial Line C-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C–2 PPP Frame Processed by PPP API C-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C–3 Serial Interface (SI) Abstraction C-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1
Introduction
This chapter serves as an introduction to the programming API reference for
the TMS320C6000 TCP/IP Network Developer’s Kit (NDK).
Topic Page
1.1 This Document 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Additional Documentation 1-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1

This Document
1-2
1.1 This Document
This Programmer’s Reference Guide for the TCP/IP Stack Network Develop-
er’s Kit (NDK) is mainly a programming API reference guide. It is intended to
aid in the development of network applications and describes the various API
functions provided by the stack libraries.
1.1.1 Supplemental API Information
The following information appears as appendices to this document. These
sections contain optional information that may be useful in understanding the
low-level application interface, but is not required when developing traditional
network applications.
-Appendix A: Internal TCP/IP Stack Library Functions
The stack library internal function specification describes a subset of the
low level programming interface to the stack. These functions allow the
application writer to make use of kernel level function APIs. As a general
rule, it is not necessary to use this API for application development, al-
though some of this sample application included in the NDK make these
use of these function calls.
-Appendix B: Network Address Translation
The stack library includes Network Address Translation module. This ap-
pendix describes the operational theory of NAT, and how to use the NAT
functions included in the library.
-Appendix C: Point to Point Protocol
The stack library has internal device sections for both traditional Ethernet,
and PPP. The PPP module can act as PPP client, server, or both (assum-
ing multiple interfaces). This appendix describes the operation of the PPP
module, the PPP over Ethernet (PPPoE) module, and how to interface an
HDLC based serial device. More information on the serial interface is sup-
plied in the NDK Porting Guide.
-Appendix D: Hardware Abstraction Layer
Appendix D describes the hardware and operating system interfaces used
by the stack. It also illustrates how the device layer may be ported to a new
hardware platform. However, the NDK Porting Guide is the primary source
of information used when porting the stack library to a new platform.
-Appendix E: Web Programming with the HTTP Server
Included with the NDK is a standard set of network services, including a
HTTP protocol server. This server includes support for an embedded file

Additional Documentation
1-3
Introduction
system and CGI POST functionality. This appendix describes how to add
web page content and CGI functions to a network application using the
HTTP server, including documenting the HTTP server’s web content API.
1.2 Additional Documentation
The following additional documents are also available.
1.2.1 TMS320C6000 TCP/IP NDK User’s Guide
Although this Programmer’s Reference Guide will be the central reference
document used when programming the stack, users should first refer to the
TCP/IP NDK User’s Guide to familiarize themselves with the stack libraries,
and in using the stack with DSP/BIOS and Code Composer Studio.
The TCP/IP NDK User’s Guide contains the following information about the
TCP/IP NDK:
-TCP/IP NDK Installation and Test
-Running the Example Applications
-TCP/IP Stack Library Overview
-Network Application Development
1.2.2 TMS320C6000 TCP/IP NDK Porting Guide
The NDK Porting Guide describes the inner workings of the individual stack
layers.
The TCP/IP stack is designed to be executed in different operating modes with
varying types of scheduling and exclusion methods. The NDK Porting Guide
describes the NETCTRL and OS layers of the stack and how to adjust them
to fit any environment.
The stack is hardware dependent at its HAL and SERIAL interface layers, but
even these layers are divided into hardware dependent and independent por-
tions. The NDK Porting Guide describes these layers, and discusses how to
port device drivers for Ethernet, system timers, and serial devices.