ZiLOG EZ80F91NAA Reference guide

ZiLOG Worldwide Headquarters • 532 Race Street • San Jose, CA 95126

Telephone: 408.558.8500 • Fax: 408.558.8300 • www.

zilog.com

eZ80

®

Family of Microprocessors

ZiLOG TCP/IP Software

Suite v1.3.4

Reference Manual

RM000809-0306

This publication is subject to replacement by a later edition. To determine whether a later

edition exists, or to request copies of publications, contact:

ZiLOG Worldwide Headquarters

532 Race Street

San Jose, CA 95126

Telephone: 408.558.8500

Fax: 408.558.8300

www.

zilog.com

Document Disclaimer

ZiLOG is a registered trademark of ZiLOG Inc. in the United States and in other countries. All other products

and/or service names mentioned herein may be trademarks of the companies with which they are associated.

applications, or technology described is intended to suggest possible uses and may be superseded. ZiLOG,

INC. DOES NOT ASSUME LIABILITY FOR OR PROVIDE A REPRESENTATION OF ACCURACY OF

THE INFORMATION, DEVICES, OR TECHNOLOGY DESCRIBED IN THIS DOCUMENT. ZiLOG

ALSO DOES NOT ASSUME LIABILITY FOR INTELLECTUAL PROPERTY INFRINGEMENT

RELATED IN ANY MANNER TO USE OF INFORMATION, DEVICES, OR TECHNOLOGY

DESCRIBED HEREIN OR OTHERWISE. Devices sold by ZiLOG, Inc. are covered by warranty and

limitation of liability provisions appearing in the ZiLOG, Inc. Terms and Conditions of Sale. ZiLOG, Inc.

makes no warranty of merchantability or fitness for any purpose Except with the express written approval of

ZiLOG, use of information, devices, or technology as critical components of life support systems is not

authorized. No licenses are conveyed, implicitly or otherwise, by this document under any intellectual

property rights.

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 Revision History

iii

Revision History

Each instance in the Revision History reflects a change to this document

from its previous revision. For more details, refer to the corresponding

pages or appropriate links given in the table below.

Date

Revision

Level Section Description

Page

No.

JUN 03 01 Original issue. All

DEC 03 02 Modified for ZTP v1.2 release. All

MAR 04 03 Modified for ZTP v1.3 release. All

APR 04 04 ZTP Device Driver

APIs

init_dev device driver API renamed to

initialize; headers changed.

360

MAY 04 05 How to Use SSL

Modified SSL section for ZTP v1.3.1 release. 150

Kernel Macros

Added kernel macros section. 342

AUG 04 06

ZTP Configuration Configuration section updated. 39

JAN 05 07 Formatted to current publication standards. All

ZTP API Reference

Many new APIs added; minor updates. 217

MAR 05 08 Modified for ZTP v1.3.4 release; removed Preliminary designation

from document.

All

MAR 06 09 Added the registered trademark symbol (®) for eZ80Acclaim! and

eZ80.

All

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

Revision History RM000809-0306

iv

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 Table of Contents

v

Table of Contents

Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

List of Figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv

List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

ZTP Manual Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Related Software Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

ZTP Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

System Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

ZTP Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Getting Started with ZTP and ZDS II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Connecting the Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Running a Sample ZTP Application . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Creating a New ZTP Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Working with Flash-Based Projects . . . . . . . . . . . . . . . . . . . . . . . . . . .11

ZTP Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Hardware Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Optional Hardware Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

ZTP OS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Operating System Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Operating System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

Table of Contents RM000809-0306

vi

Process State Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Real-Time Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Protocol Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

ZTP HTTP Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Understanding Webserver Web Pages . . . . . . . . . . . . . . . . . . . . . . . . 35

Understanding Webservers on Computer Systems . . . . . . . . . . . . . . . 36

Understanding Webservers on Embedded Systems . . . . . . . . . . . . . . 36

ZTP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

ZDS II Target Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Hardware Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

eZ80_HW_Config.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

F91_phy.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

ipw_ez80.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

XINU System Timer and Interrupt Vector . . . . . . . . . . . . . . . . . . . . . 46

Minimum Stack Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

EMAC Driver Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

DHCP Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

UART Usage and Interrupt Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Command Prompt Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Maximum Number of Ethernet Packets . . . . . . . . . . . . . . . . . . . . . . . 50

net_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

modem.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

serial_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Operating System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

shell_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

netcmds.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

sys_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

panic.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

null_proc.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Network Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

bootinfo.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

dgram_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 Table of Contents

vii

ip_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

ppp_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

snmib.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

snmp_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

tcp_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72

ssl_conf.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72

Build Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Preprocessor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Target Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

Linker Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

Porting ZTP Applications to a Custom Hardware Platform . . . . . . . . .83

ZTP Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86

Using ZTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

How to Use Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

eZ80

®

Interrupt Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

Using the ZTP Interrupt Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

How to Use Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

How to Use DHCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

How to Use RARP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

How to Use ICMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109

How to Use IGMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110

How to Use TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

TCP Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

The ZTP TCP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

How to Use HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

HTTP Application Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

The http_init Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126

CGI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Building Web Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

How to Use TFTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141

How to Use SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

Table of Contents RM000809-0306

viii

How to Use Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

How to Use DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

How to Use IGMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

How to Use TIMEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

timed_738_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

How to Use PPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

How to Use SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

SSL Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Initializing the SSL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Creating x.509 Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

The ZTP SSL2 Cipher Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Creating an SSL Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

How to Use the HTTPS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

How to Use the Serial Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

How to Use the Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

How to Use SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

How to Create a Custom Ethernet Driver . . . . . . . . . . . . . . . . . . . . . . . . 203

ZTP Ethernet Driver Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

The EMAC Driver Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Implementing a New Ethernet Driver . . . . . . . . . . . . . . . . . . . . . . . . 206

ZTP API Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Kernel APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Process Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

KE_TaskChangePrio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

KE_TaskCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

KE_TaskGetCurPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

KE_TaskGetPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

KE_TaskGetPrio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

KE_TaskDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

KE_TaskResume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

KE_TaskSleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

KE_TaskSleep10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 Table of Contents

ix

KE_TaskSleep100 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246

KE_TaskSuspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248

KE_TaskSuspendCur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

KE_TaskUnsleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253

Semaphore Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254

KE_SemCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256

KE_SemCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258

KE_SemDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260

KE_SemRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263

KE_SemReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266

KE_SemAcquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268

Mailbox Messaging Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270

KE_MBoxSend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271

KE_MBoxReceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273

KE_MBoxRcvTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275

KE_MBoxRecvClr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277

Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .278

KE_BpoolCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282

KE_BpoolDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284

KE_BpoolFreeBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286

KE_BpoolGetBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288

getmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290

freemem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292

querymem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294

addmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295

Message Port Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296

KE_PortCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298

KE_PortCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300

KE_PortDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302

KE_PortReceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305

KE_PortReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308

KE_PortSend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

Table of Contents RM000809-0306

x

KE_PortSendUnique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Miscellaneous OS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

set_evec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

kprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

panic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

KE_DisablePreempt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

KE_EnablePreempt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

KE_RestorePreempt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

KE_IsrResched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

KE_TaskGetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

KE_TaskSetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

KE_KernelInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Kernel Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

KE_Reboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

KE_EnableMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

KE_DisableMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

KE_EnterISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

KE_ExitISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

KE_CriticalBegin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

KE_CriticalEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

ZTP Device Driver APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

adddevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

KE_AddDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

peek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

getc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

putc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 Table of Contents

xi

seek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396

ZTP Networking APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398

UDP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398

udp_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .401

udp_add_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403

open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404

control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407

read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .411

write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414

peek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417

close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

TCP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420

tcp_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423

tcp_add_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .426

open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427

control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431

read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436

write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .440

peek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .443

getc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .445

putc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .446

close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447

ARP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .449

arp_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450

arp_add_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453

get_arp_mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .454

ICMP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456

icmp_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457

icmp_add_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .459

ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .460

IGMP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .461

igmp_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .463

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

Table of Contents RM000809-0306

xii

hgjoin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

hgleave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467

igmp_add_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

Ethernet Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

emac_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

eth_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

Is_Ethernet_Connected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

PPP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

ppp_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

ppp_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

ppp_resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

get_ppp_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

Miscellaneous Network Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 486

netstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488

name2ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

ip2name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492

dot2ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494

ip2dot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

timed_738_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

timed_738_gettime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

HTTP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501

http_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502

Advanced Topic: Creating Your Own Method Handler . . . . . . . . . . 510

ZTP C Run-Time Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511

xc_ascdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512

xc_fprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

xc_sprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514

xc_strcasecmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

xc_index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

ZTP Shell Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

arp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519

bpool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 Table of Contents

xiii

conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .523

date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .525

devs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .526

dg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .530

echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531

exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .532

tftpdemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .533

hang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .534

help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .535

ifstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .536

igmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .537

kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .538

mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .539

mem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .540

netstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .542

ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .544

ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .545

port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .546

pppmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .548

pppopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .550

pppresume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .552

pppstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .553

pppstop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .555

ps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556

reboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .559

route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .560

routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .563

sem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .565

sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .567

time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .568

timerq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .569

udplisten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .570

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

Table of Contents RM000809-0306

xiv

udpping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 List of Figures

xv

List of Figures

Figure 1. ZTP Protocol Stack Software Block Diagram . . . . . . . . . . .7

Figure 2. XINU Process States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Figure 3. Symmetric Cipher Encryption and Decryption . . . . . . . . .155

Figure 4. Asymmetric Cipher Encryption and Decryption . . . . . . .156

Figure 5. Internet Options Window . . . . . . . . . . . . . . . . . . . . . . . . .170

Figure 6. Security Alert Warning Message . . . . . . . . . . . . . . . . . . .171

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

List of Figures RM000809-0306

xvi

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 List of Tables

xvii

List of Tables

Table 1. ZTP Protocol Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Table 2. Modemchat Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68

Table 3. ZTP Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

Table 4. ZTP HTTP Request Methods . . . . . . . . . . . . . . . . . . . . . .125

Table 5. HTTP Reply Response Codes . . . . . . . . . . . . . . . . . . . . . .126

Table 6. Web Page Filename Extensions . . . . . . . . . . . . . . . . . . . .141

Table 7. Default IP Addresses by Protocol . . . . . . . . . . . . . . . . . . .150

Table 8. SSL2 Cipher Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . .165

Table 9. ASN1-Supported Primitive Data Types . . . . . . . . . . . . . .180

Table 10. ZTP API Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221

Table 11. ZTP OS Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222

Table 12. Kernel APIs as a Function of State . . . . . . . . . . . . . . . . . .223

Table 13. Process Manipulation Functions . . . . . . . . . . . . . . . . . . . .223

Table 14. Semaphore Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .255

Table 15. Mailbox Messaging Functions . . . . . . . . . . . . . . . . . . . . .270

Table 16. Memory Manager Functions . . . . . . . . . . . . . . . . . . . . . . .281

Table 17. Message Port Functions . . . . . . . . . . . . . . . . . . . . . . . . . .297

Table 18. Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317

Table 19. Kernel Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346

Table 20. ZTP Device Driver APIs . . . . . . . . . . . . . . . . . . . . . . . . . .368

Table 21. Stack User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . .398

Table 22. Datagram Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399

Table 23. TCP Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .421

Table 24. HTTP Method Requests . . . . . . . . . . . . . . . . . . . . . . . . . .501

Table 25. HTTP API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .507

Table 26. Library Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

List of Tables RM000809-0306

xviii

Table 27. Shell Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

ZiLOG TCP/IP Software Suite v1.3.4

Reference Manual

RM000809-0306 About This Manual

1

ZTP Manual Objectives

This reference manual describes the architecture and application pro-

gramming interface (API) to the ZiLOG TCP/IP (ZTP) Software Suite,

which features a set of TCP/IP software libraries and a version of the

XINU operating system for ZiLOG’s eZ80Acclaim!

®

microprocessors/

controllers. The ZTP libraries require minimal memory and transform the

devices into efficient embedded webservers.

About This Manual

ZiLOG recommends that you read and understand everything in this man-

ual before using this product to develop code. However, we recognize that

there are different styles of learning. Therefore, this manual is designed to

be used either as a procedural manual or a reference guide to important

data.

Intended Audience

This document is written for ZiLOG customers who are experienced at

working with microprocessors and who understand networking funda-

mentals.

Organization

This Reference Manual is divided into several sections, starting with an

introduction section and concluding with reference material. Each section

details a specific topic about the ZTP product.

ZTP Overview

Presents an overview of the ZTP operating system, network protocols,

and system resources required for ZTP.

ZTP Configuration

Contains information describing the setup and configuration of ZTP.

ZiLOG TCP/IP Software Suite v1.3.4

eZ80

®

Family of Microprocessors

ZTP Manual Objectives RM000809-0306

2

Using ZTP

Explains how to develop applications using the ZTP software suite and

the XINU Operating System.

ZTP API Reference

Describes the ZTP programming interface to the kernel, networking mod-

ule, and C run time library functions.

ZTP Shell Command Reference

Describes the shell interface for monitoring ZTP functions.

Related Software Releases

Refer to the ZiLOG website for latest release of ZTP and updates to this

manual.

Conventions

The following assumptions and conventions are adopted to provide clarity

and ease of use:

Courier Typeface

Commands, code lines and fragments, bits, equations, hexadecimal

addresses, and various executable items are distinguished from general

text by the use of the

Courier typeface.

Hexadecimal Values

Hexadecimal values are designated by a lowercase h and appear in the

Courier typeface.

•

Example: STAT is set to F8h.

Asterisks

An asterisk preceding a parameter denotes the parameter as a pointer.

Page is loading ...

ZiLOG EZ80F91NAA Reference guide

This manual is also suitable for

ZiLOG EZ80F91NAA Reference guide

Related papers

Other documents