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.

2-1
Operating System Abstraction API
In order to keep the stack system portable, it was coded to a very compact Op-
erating System Abstraction. The stack can execute in any operating environ-
ment by porting the functions described here. Most of these functions will map
directly to a native OS counterpart.
Applications programmers that program to this API are assured that their ap-
plications will execute on any system to which this abstraction is ported.
Topic Page
2.1 Operating System Configuration 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Task Support 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Semaphore Support 2-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Memory Allocation Report 2-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Print and Debug Support 2-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6 File I/O Support for Embedded Systems 2-17. . . . . . . . . . . . . . . . . . . . . . .
Chapter 2

Operating System Configuration
2-2
2.1 Operating System Configuration
2.1.1 Synopsis
The OS has a couple of configuration options that regulate its behavior. These
are stored in a data structure. The types of properties defined in the structure
are those that would typically be macros, but using a data structure allows the
values to be changed without rebuilding the libraries.
The structure is described here for completeness, but applications should use
the configuration system to make alterations to these values. The configura-
tion system is described later in this document.
2.1.2 Configuration Structure
The stack internal configuration structure is _oscfg. Any element in this struc-
ture may be modified before the system is booted. System initialization is cov-
ered later in this document.
The _oscfg structure of type OSENVCFG, which is defined as follows:
// Configuration Structure
typedef struct _osenvcfg {
uint DbgPrintLevel; // Debug message print threshold
uint DbgAbortLevel; // Debug message sys abort threshold
int TaskPriLow; // Lowest priority for stack task
int TaskPriNorm; // Normal priority for stack task
int TaskPriHigh; // High priority for stack task
int TaskPriKern; // Kernel–level priority (highest)
int TaskStkLow; // Minimum stack size
int TaskStkNorm; // Normal stack size
int TaskStkHigh; // Stack size for high volume tasks
} OSENVCFG;
The structure entries as defined as follows:
Debug Message Print Threshold
_oscfg.DbgPrintLevel
Default Value DBG_INFO
Description This is the lowest severity level of a system debug message (call to DbgPrintf()
function) that will be recorded into the debug log. The threshold may be raised.
The legal values for this variable are: DBG_INFO, DBG_WARN,
DBG_ERROR, and DBG_NONE.

Operating System Configuration
2-3
Operating System Abstraction API
Debug Message Abort Threshold
_oscfg.DbgAbortLevel
Default Value DBG_ERROR
Description This is the lowest severity level of a system debug message (call to DbgPrintf()
function) that will result in a system shutdown (call to NC_NetSop()). The
threshold may be raised. The legal values for this variable are: DBG_INFO,
DBG_WARN, DBG_ERROR, and DBG_NONE.
Priority Level for Low Priority Stack Task
_oscfg.TaskPriLow
Default Value 3
Description This is the priority at which low priority stack task threads are set. Setting a
thread to a lower priority than this will not disrupt the system, but no system
or service supplied in this package will attempt it.
Priority Level for Normal Priority for Stack Task
_oscfg.TaskPriNorm
Default Value 5
Description This is the priority at which most stack task threads are set. Task threads that
are created by the system or services will usually run at this level.
Priority Level for High Priority for Stack Task
_oscfg.TaskPriHigh
Default Value 7
Description This is the priority at which high priority stack task threads are set. Setting a
thread at a higher priority than this may disrupt the system and cause unpre-
dictable behavior if the thread calls any stack related functions. High priority
tasks (like interrupts) can execute at higher priority levels, but should signal
lower priority tasks to perform any required stack functions.
Priority Level of High Priority Kernel Tasks
_oscfg.TaskPriKern
Default Value 8
Description This is the priority that tasks threads execute at when they are inside the ker-
nel. Setting tasks to this priority level ensures that they will not be disrupted
by another task calling stack functions. The proper method of entering the ker-
nel is to call llEnter() and llExit(). This functions are discussed in the appen-
dices, as they are not required for the applications programmer.

Operating System Configuration
2-4
Minimum Task Stack Size
_oscfg.TaskStkLow
Default Value 3072
Description This is the stack size used for network task that do very little network process-
ing, or do not use TCP.
Normal Task Stack Size
_oscfg.TaskStkNorm
Default Value 4096
Description This is the stack size used for a network task with an average network band-
width using TCP. It is used for the majority of network tasks in the network tools
library that use TCP.
High Volume Task Stack Size
_oscfg.TaskStkHigh
Default Value 5120
Description This is the stack size used to network tasks that require a high network band-
width using TCP. It is also used for tasks calling HTTP CGI functions.

Task Support
2-5
Operating System Abstraction API
2.2 Task Support
2.2.1 Synopsis
The task object provides a method of manipulating task threads using a gener-
ic task handle. Task threads are executed on a priority based method, with a
least–recently–run algorithm used on those with equal priority. Each task
thread has its own private stack.
2.2.2 Function Overview
The Task Object access functions (in functional order) are as follows:
TaskCreate() Create new task thread
TaskDestroy() Destroy a task thread
TaskSelf() Get handle to current task thread
TaskExit() Exit (terminate) current task thread
TaskYield() Yield to another task thread at the same priority
TaskSleep() Block a task thread for a period of time
TaskBlock() Block a task thread
TaskSetPri() Set task thread priority level
TaskGetPri() Get task thread priority level
TaskSetEnv() Assign one of three private environment handles to
task thread
TaskGetEnv() Retrieve one of three private environment handles
2.2.3 Task API Functions
Block Task From Execution
TaskBlock
Syntax void TaskBlock( HANDLE hTask );
Parameter(s) hTask Handle to target task
Return Value nothing
Description Permanently blocks the specified task from execution.
Calling this function may cause a task switch.
Create a Task Thread
TaskCreate
Syntax HANDLE TaskCreate( void(*pFun)(), char *Name, int Priority, uint Stack-
Size,UINT32 Arg1, UINT32 Arg2, UINT32 Arg3 );
Parameter(s) pFun Pointer to task entry-point function
Name NULL terminated task name (truncated after 11 characters)

Task Support
2-6
Priority Task priority level (0–15)
StackSize Task stack size
Arg1 Optional task function argument 1
Arg2 Optional task function argument 2
Arg3 Optional task function argument 3
Return Value Returns a Task Handle on success or NULL on memory failure.
Description Creates a new task object. If successful, TaskCreate() returns a handle to the
newly created task.
The task name supplied in Name is used for informational purposes only, and
does not need to be unique.
The task priority specified in Priority determines the task thread’s priority rela-
tive to other tasks in the system. The value of Priority is constrained only by
the size of an int on the target environment, but a range of 0 to 15 is recom-
mended. 0 is the lowest priority and should be reserved for an idle task. If the
specified priority is negative, the task is blocked.
The task stack size specified by StackSize is not examined or adjusted by the
create function. The size should be made compatible with the native environ-
ment (a multiple of 4 bytes should be sufficient).
Arg1 through Arg3 are optional arguments that can be passed to the calling
function (they are always pushed onto the stack, but the task function need not
reference them).
There is no limit to the number of tasks that can be installed in the system. The
only possible failure on TaskCreate() is a memory allocation error.
If the priority level of the new task is higher than the priority level of the current
task. The entrypoint function pFun is executed immediately (before Task-
Create() returns to the caller).
Calling this function may cause a task switch.

Task Support
2-7
Operating System Abstraction API
Destroy a Task Thread
TaskDestroy
Syntax void TaskDestroy( HANDLE hTask );
Parameter(s) hTask Handle to target task
Return Value nothing
Description Terminates execution of the task object specified by the supplied handle
hTask, and frees task object from system memory. Note that memory allocated
by the task thread is not associated with the task thread and must be freed
manually by the programmer.
Exit a Task Thread
TaskExit
Syntax void TaskExit();
Parameter(s) none
Return Value Does not return
Description This function is used to gracefully exit a task thread. It should always be called
immediately before the task entry-point function is about to return, but it may
be called from anywhere.
Get Task Environment Handle
TaskGetEnv
Syntax HANDLE TaskGetEnv( HANDLE hTask, int Slot );
Parameter(s) hTask Handle to target task
Slot Environment slot to use (1–3)
Return Value Private environment handle or NULL
Description NOTE: This function is currently not available under DSP/BIOS
Returns a private environment handle for the supplied task handle hTask
which was previously stored with the TaskSetEnv() function. The slot specified
in Slot specifies the address (1–3) of the environment handle. There are actu-
ally four slots, but slot 0 is reserved.
Get Task Priority
TaskGetPri
Syntax int TaskGetPri( HANDLE hTask );
Parameter(s) hTask Handle to target task
Return Value Task priority level
Description Returns the priority of the target task. See TaskSetPri() for more information
on priority.

Task Support
2-8
Get the Handle to the Currently Executing Task Thread
TaskSelf
Syntax HANDLE TaskSelf();
Parameter(s) none
Return Value Handle to currently executing thread, or NULL on error
Description Returns the task handle of the currently executing task thread. This function
is used mainly in other task object calls where the caller wishes to operate on
the current thread, but does not know the current thread’s handle.
If called on an illegal (system) thread, this function returns NULL. Only certain
implementations of the OS even have a system thread, and then, no user code
should ever be executed on it. A NULL may also result if Task functions are
called before the operating system is initialized.
Set Task Environment Handle
TaskSetEnv
Syntax void TaskSetEnv( HANDLE hTask, int Slot, HANDLE hEnv );
Parameter(s) hTask Handle to target task
Slot Environment slot to use (1–3)
hEnv Private environment handle
Return Value nothing
Description NOTE: This function is currently not available under DSP/BIOS
Sets and stores a private environment handle for the supplied task handle
hTask. This handle can be later retrieved by TaskGetEnv(). The slot specified
inSlot assigns an address (1–3) to the environment handle. There are actually
four slots, but slot 0 is reserved.
Environment handles can be used to associate private data with a task thread.
This is useful when multiple threads share the same code base, but require
their own instance of static data.

Task Support
2-9
Operating System Abstraction API
Set Task Priority
TaskSetPri
Syntax int TaskSetPri( HANDLE hTask, int Priority );
Parameter(s) hTask Handle to target task
Priority Task priority level
Return Value Previous task priority level
Description Sets the priority of the target task to the specified value. The value of Priority
is constrained only by the size of an int on the target environment, but a range
of 0 to 15 is recommended. 0 is the lowest priority and should be reserved for
an idle task. If the specified priority is negative, the task is blocked.
Calling this function may cause a task switch.
Sleep Task for Period of Time
TaskSleep
Syntax void TaskSleep( UINT32 Delay );
Parameter(s) Delay Time (in milliseconds) of sleep
Return Value nothing
Description Sleeps the calling task for a period of time as supplied in Delay. The sleep time
can not be zero.
Calling this function may cause a task switch.
Yield Execution to Another Task Thread
TaskYield
Syntax void TaskYield();
Parameter(s) none
Return Value none
Description This function is used to yield execution to another thread. Its only function is
to cause a round-robin task switch among “ready”task threads executing at
the same priority level.
This function always causes a task switch, however the original calling task
may be the next to execute.

Semaphore Support
2-10
2.3 Semaphore Support
2.3.1 Synopsis
The semaphore object provides a method of manipulating counting sema-
phores using a generic handle.
Semaphores can be used for both task synchronization and mutual exclusion.
2.3.2 Function Overview
The Semaphore Object access functions (in functional order) are as follows:
SemCreate() Create new semaphore
SemDelete() Delete semaphore
SemPend() Wait on semaphore, optionally for a period of time
SemCount() Get the current semaphore count
SemPost() Release semaphore –increment count
SemReset() Reset semaphore and set new count
2.3.3 Semaphore API Functions
Create New Semaphore
SemCreate
Syntax HANDLE SemCreate( int Count );
Parameter(s) Count Initial semaphore count
Return Value Handle to semaphore or NULL on error
Description Creates a new semaphore object with an initial count.
Get Current Semaphore Count
SemCount
Syntax int SemCount( HANDLE hSem );
Parameter(s) hSem Handle to Semaphore
Return Value Current semaphore count
Description Returns the current count of the semaphore object.