softwa re developmen t kit s-7600abooks.mhprofessional.com/engineering/updatezone/... · s-7600a...

S-7600A TCP/IP NETWORK PROTOCOL STACK LSI Revision 1.1

Seiko Instruments Inc.

Software Development Kit

S-7600A

Network Stack Driver APIs

Seiko Instruments USA Inc.

Tel +1-909-934-9334Fax +1-909-975-5699

2990 West Lomita BoulevardTorrance, California 90505

iReady CorporationiReady Corporation iiii

TABLE OF CONTENTS

CHAPTER 1 INTRODUCTION.......................................................................... 1-1

ABOUT IREADY DRIVERS....................................................................................... 1-2Overview........................................................................................................... 1-2Time- and Task-related Services......................................................................... 1-2

DRIVER PACKAGE ................................................................................................. 1-4

CHAPTER 2 STACK FUNCTIONS .................................................................... 2-1

STACK FUNCTIONS ................................................................................................ 2-2iStacApi Function Overview .............................................................................. 2-2IsInitStack ......................................................................................................... 2-4IsPPPConnect ................................................................................................... 2-4IsPPPDisconnect............................................................................................... 2-5IsPPPCheck ...................................................................................................... 2-5IsPPPKeepAlive ................................................................................................ 2-5IsPPPMaintain.................................................................................................. 2-6IsGetOurIP ....................................................................................................... 2-6 Sample Code Reference .................................................................................... 2-7

CHAPTER 3 SOCKET FUNCTIONS ................................................................. 3-1

SOCKET FUNCTIONS .............................................................................................. 3-2IsInitSocket ....................................................................................................... 3-4IsTCPConnect ................................................................................................... 3-4IsTCPListen ...................................................................................................... 3-5IsTCPRead........................................................................................................ 3-6IsTCPWrite ....................................................................................................... 3-7IsTCPClose ....................................................................................................... 3-7IsTCPAbort ....................................................................................................... 3-8IsUDPCreate..................................................................................................... 3-8IsUDPRead ....................................................................................................... 3-9IsUDPWrite......................................................................................................3-10IsUDPRelease ..................................................................................................3-11IsUDPAbort......................................................................................................3-11Sample Code Reference ....................................................................................3-12

CHAPTER 4 ITASK FUNCTIONS ..................................................................... 4-1

OVERVIEW ............................................................................................................ 4-2Tunable Parameters .......................................................................................... 4-2

ITASK FUNCTIONS ................................................................................................. 4-3ItaskInit............................................................................................................. 4-4ItaskCbAdd ....................................................................................................... 4-4ItaskCbRemove.................................................................................................. 4-5ItaskTcbAdd ...................................................................................................... 4-5ItaskTcbRemove................................................................................................. 4-6ItaskCallback .................................................................................................... 4-6ItaskTicCnt........................................................................................................ 4-7Sample Code Reference ..................................................................................... 4-8

CHAPTER 5 BUILDING AND PORTING INSTRUCTIONS............................ 5-1

OVERVIEW ............................................................................................................ 5-2LIBRARY BUILD INSTRUCTION ............................................................................... 5-2

Builds................................................................................................................ 5-4TROUBLESHOOTING TIPS ....................................................................................... 5-6

T A B L E O F C O N T E N T S

iiiiii iReady iReady Network Stack Network Stack Driver APIsDriver APIs

APPLICATION BUILD ENVIRONMENT....................................................................... 5-7PORTING TO ANOTHER RTOS ................................................................................. 5-7

AppendicesAppendix A iSys.h .............................................................................................A-2Appendix B iSys.c (uCos) ..................................................................................B-2iSys.C (NORTi) ..................................................................................................B-3iSys.C (iTRON)..................................................................................................B-4

Introduction

Chapter

1

C H A P T E R 1 N e t w o r k S t a c k D r i v e r

iReady CorporationiReady Corporation 1-1-22 Confidential and ProprietaryConfidential and Proprietary

About iReady Drivers

Overview

The iReady Hardware Driver APIs are a set of APIs that a software application can useto control the functionality provided by iReady hardware. These drivers are platform,processor, and operating system independent. They are designed to support usage inhighly integrated embedded systems that run in a multitasking environment.

These APIs are provided in C source code format, along with a build environment,documentation, and sample code. The drivers are compiled into software libraries thatare linked into the application. The APIs provide an easy and powerful method to useiReady hardware in an application. This document describes the iReady Network StackDriver APIs.

The platform/processor independence is achieved by abstracting the hardware accessfunctionality in iHwIface.h and implementing it (iHwIface.c) separately. Thisparticular implementation allows recognition of the platform specifics (indexed or directaccess to the hardware), processor specifics (little/big endian) and OS specifics(atomicity with respect to preemption).

The iReady hardware targets use in embedded systems that are asynchronously drivenby real-time events (for example, user interactions, network messages, timers). Thedrivers are preemptive, multitasking-friendly while still OS-neutral. This is achieved byabstracting the necessary services from the OS in iSys.h (see Appendix A) andimplementing them in iSys.c (see Appendix B) in the optimal way for each targeted OS.The OS-specific services used by the drivers are time-related and task-related.

Time- and Task-related Services

Time-related services are necessary for the support of timeouts in the iReady drivers.These services are normally provided by the operating system used in the target system.In applications that use drivers that do not require the support of timeouts (for exampleITMO_INFINITE and ITMO_NO_RETRY), time-related services can be faked withdummy functions if those services are not provided by the operating system.

The iReady drivers access the time (absolute or relative) with two functions thatcomprise the abstraction layer between the drivers and the operating system. The firstfunction obtains the time in an operating system-dependent format and stores this valuein the memory space of the calling task. The second function compares the timeobtained by the first function to the current time and returns the difference between thetwo times in a format that the drivers understand (actual time elapsed). The resolutionand accuracy of the time is dependent on the underlying operating system.

The task-related services include timed sleep and synchronization mechanisms. Thetimed sleep, used to create delays and initiate task switches, is implemented by inherentfunctions of the particular OS. The synchronization mechanism is used forasynchronous communication of events between the interrupt level and the task level.

I N T R O D U C T I O N

1-1-33 iReady iReady Network Stack Network Stack Driver APIsDriver APIs

The mechanism is an object that is defined by a state, and supports four operations:

1. initialize Brings the state to a known, consistent state.

2. pend Blocks the executing task for a specific period of time unless it is released bya post or abort operation.

3. post If a task is blocked on this synchronization mechanism (executed pendoperation), it is released.

4. abort The same as the post operation, but pend will return a code that identifies theabort state.

Using this mechanism, a task that executes an operation in the driver waiting forresources can notify the OS that it will release the CPU for other tasks until it is able tocontinue executing.



Driver PackageThe driver application interface is classified into two parts. Each part corresponds to aniReady hardware subsystem:

♦ iStacApi for the Network Stack

♦ iSockApi for the Socket Engine

The iReady API functions (iStacApi, iSockApi) call the iSys functions and eliminatethe need for users to understand iSys.

The iSys encapsulates the implementation that is dependent on the RTOS. The currentiSys supports ITRON 3.0, NORTi, and microC/OS operating systems. The target RTOScan be specified at build time.

As an alternative to an RTOS, iReady has developed a small (2K) single-task kernel(Itask).

Sample application, text/echo.c, is used for the TCP Socket.

File Contents

iHwIface.h Defines the access to the core registers.

iDrvUtil.h Defines the utilities the drivers use.

iXxxxApi.h Defines the API for the Xxxx driver.

ixxxxpri.h Private header file, includes register displacement, masks.

ixxxx.c Contains the driver implementation.

iSys.h Defines abstraction of the OS dependencies.

iSys.c Implements the abstraction of the OS dependencies.

ixxxx.lib The driver library with which the application can link.

Note: xxxx corresponds to stac/sock and Xxxx corresponds to Stac/Sock.

Stack FunctionsThis chapter is a guide to each of the iStac API functions, includingparameters and data structures, used in the iReady Application ProgramInterface.

Chapter

2



Stack Functions

The stack functions provide an interface to the iReady hardware link layer (PPP).Table 2-1 contains an overview of the functions that operate the network stack.

Table 2-1 iStacApi Function Overview

Function name Purpose

IsInitStack Initializes the iReady hardware stacksubsystem.

IsPPPConnect* Establishes a PPP connection.

IsPPPDisconnect Shuts down a PPP connection.

IsPPPCheck Checks if the PPP connection is up.

IsPPPKeepAlive* Keeps the PPP connection alive.

IsGetOurIP Gets our current IP address.

* Blocking—should not be used in critical sections.

Some functions will block if the following conditions occur:

• All of the conditions for completion are not yet fulfilled (refer to the functioncalls for specific conditions).

• The timeout parameter is not ITMO_NO_RETRY.

A multi-tasking OS allows other tasks to execute during the periods when afunction blocks. If the OS does not permit multi-tasking, the application cancontrol it by specifying ITMO_NO_RETRY.

S T A C K F U N C T I O N S ( i S t a c A p i )


Table 2-2 contains the return code (RET_CODE) values that specify possible returnconditions in the stack operations. The iStacAPI-specific return codes are definedalong with the function prototypes contained in the header file, iStacApi.h. Themore general return codes (for example, RET_CODE_OK) are defined in theheader file, iReady.h.

Table 2-2 iStacApi Return Codes

Return Code Error Condition

RET_CODE_OK No error.

RET_CODE_FAIL General failure.

ISRC_HW_ABSENT iReady hardware was not accessible.

ISRC_MODEM_ABSENT Modem cannot be recognized by theiReady hardware.

ISRC_MDM_RING Modem returned a ring error.

ISRC_MDM_BUSY Modem returned a busy error.

ISRC_CODE_BAD_PARAM Function was invoked with an invalidparameter.

ISRC_MODEM_CONFIG Failed to configure the modem.

ISRC_PPP_DOWN PPP connection was down.

ISRC_CONNECT_FAILED Modem failed to connect.

ISRC_MDM_CARRIER No carrier detected.

ISRC_MDM_DIALTONE No dial tone detected.

ISRC_MDM_ERROR Modem indicated an error.

ISRC_MDM_ANSWER Number dialed not answered by themodem.



IsInitStack

This function initializes the iReady hardware stack subsystem. This call should bemade before other stack functions are used.

Prototype RET_CODE IsInitStack()

Input(s) None

Output(s) None

Returns RET_CODE_OK

ISRC_HW_ABSENT

Blocking No

Example Reference line 37 in the Sample Code at the end of this chapter.

IsPPPConnect

This function establishes a PPP connection. The application provides all of thenecessary information for establishing the connection. This function returns whenthe connection is up, an error occurs, or the timeout has elapsed.

Prototype RET_CODE IsPPPConnect(iPPPData *pdata, iTimeouttmo)

Input(s) pdata: The structure that contains the necessary data to raise a PPP connection. The data structure depends on which hardware options are present. The following fields are currently defined:

♦ U8 useModem Used as boolean

♦ U16 baudRate The baud rate (for example, 57600)

♦ U8 auth Possible values include:

IPPP_AUTH_NONE: Authentication not offered. IPPP_AUTH_PAP: Offer PAP authentication.

♦ char *name Pointer to the user account name

♦ char *passwd Pointer to the user password

♦ char **modemInitStrings Command strings to initialize the modem

♦ char *modemDialString Dial string (e.g. “ATDP 5551212”)

♦ U8 hwFlowCtrl Activates the hardware flow control. To activate, set hwFlowCtrl to HW_FLOW_CTRL (defined in the iStacApi.h). Otherwise, set to 0.

tmo: Timeout value (in 10ms units). ITMO_INFINITE can be used for no timeout.

Output(s) None

Returns RET_CODE_OK, otherwise one of the return codes listed in Table 2-2.

Blocking Yes


The modemInitStringspointer should point to alist of string pointers.These strings will be sentto the modem during theinitialization sequence.The last item in this listshould be a NULL.



IsPPPDisconnect

This command shuts down a PPP connection.

Prototype RET_CODE IsPPPDisconnect()

Input(s) None

Output(s) None

Returns RET_CODE_OK

Blocking No


IsPPPCheck

This function checks if the PPP connection is active.

Prototype RET_CODE IsPPPCheck()

Input(s) None

Output(s) None

Returns RET_CODE_OK

ISRC_PPP_DOWN

Blocking No


IsPPPKeepAlive

This function checks if the PPP connection is up. If not, a keep alive message issent and the connection is re-established.

Prototype RET_CODE IsPPPKeepAlive(iTimeout tmo)

Input(s) tmo: Timeout value (in 10ms units).

Output(s) None

Returns RET_CODE_OK

ISRC_PPP_DOWN

Blocking Yes




IsGetOurIP

This function returns the current IP address.

Prototype RET_CODE IsGetOurIP(iIPAddr *ip)

Input(s) None

Output(s) ip: Current IP address.

Returns RET_CODE_OK

ISRC_PPP_DOWN

Blocking No




Sample Code Reference

#include <iReady.h>#include <iStacApi.h>

#define A_LONG_TIME 10000

static int do_connect = 1, was_connected = 0;static iIPAddr ip;

void dropConnection(void) {do_connect = 0;

}

ppp_task(void) {RET_CODE rc;iPPPData pdata;static char *initStrings[5];initStrings[0] = "AT+FAE=0\n"; /* "ATH"; */initStrings[1] = "ATE0\n"; /* "AT&F0"; */initStrings[2] = initStrings[3] = initStrings[4] = 0;

pdata.modemInitStrings = initStrings;

/* initialize pdata */pdata.name = "user-name";pdata.passwd = "user-pwd";initStrings[0] = "AT+FAE=0\n"; /* "ATH"; */initStrings[1] = "ATE0\n"; /* "AT&F0"; */initStrings[2] = initStrings[3] = initStrings[4] = 0;

pdata.baudRate = 57600;pppd.hwFlowCtrl = 1;pdata.useModem = 1;pdata.modemDialString = "ATDT 555-1234";pdate.auth = IPPP_AUTH_PAP;pdata.modemInitStrings = initStrings;

rc = IsInitStack();if(RET_CODE_OK == rc) {

while(do_connect) {rc = IsPPPCheck();if(RET_CODE_OK == rc) {

if(0 == was_connected)rc = IsGetOurIP(&ip);was_connected = 1;

}}else if(was_connected) {

was_connected = 0;rc = IsPPPKeepAlive(A_LONG_TIME);}

else {rc = IsPPPConnect(&pdata, A_LONG_TIME);continue;}

smallSleep(A_LONG_TIME);}

rc = IsPPPDisconnect();}

}

5

10

15

20

25

30

35

40

45

50

55

Socket FunctionsThis chapter is a guide to each of the iSockAPI functions, includingparameters and data structures, used in the iReady Application ProgramInterface.

Chapter

3



Socket Functions

The socket functions provide an interface to the iReady hardware socket subsystemthat includes TCP, IP, and UDP. Table 3-1 contains an overview of the functionsthat operate the network socket.

Table 3-1 iSockApi Functions Overview


IsInitSocket Initializes socket software components.

IsTCPConnect* Attempts to open a TCP connection.

IsTCPListen* Accepts a TCP connection.

IsTCPRead* Reads data from a TCP socket.

IsTCPWrite* Writes data to a TCP socket.

IsTCPClose* Closes a TCP socket.

IsTCPAbort Aborts an operation executed on the TCPsocket.

IsUDPCreate* Creates a listening UDP socket.

IsUDPRead* Waits for and reads a UDP message.

IsUDPWrite* Writes and sends to a UDP socket.

IsUDPRelease* Closes a UDP socket.

IsUDPAbort* Aborts an operation executed on a UDP socket.

* Blocking—should not be used in critical sections.

Some functions will block if the following conditions occur:

• All of the conditions for completion are not yet fulfilled (refer to the functioncalls for specific conditions).

• The timeout parameter is not ITMO_NO_RETRY.

A multi-tasking OS allows other tasks to execute during the periods when afunction blocks. If the OS does not permit multi-tasking, the application can controlit by specifying ITMO_NO_RETRY.

S O C K E T F U N C T I O N S ( i S o c k A p i )


Table 3-2 contains the values (typed as RET_CODE) that specify possible returnconditions in the socket operations.

Table 3-2 iSockApi Return Codes



RET_CODE_ABORT Socket connection aborted perapplication request.

ISRC_TIMEOUT Socket connection timed out.

ISRC_TERMINATED Socket connection terminated.

ISRC_RESET Socket connection reset.

ISRC_NO_AVAILABLE_SOCKET Hardware limitation—all sockets inuse.

ISRC_NOT_CONNECTED Socket was not connected.

ISRC_NOT_ACTIVATED Socket was not activated.

ISRC_UDP_TOO_MUCH_DATA Message size not supported.

ISRC_NOT_WRITABLE Socket was not in a writable TCPstate.

ISRC_SOCKET_CLOSING Socket was being closed.

ISRC_BAD_SOCKET_ID Socket ID was incorrect.

Table 3-3 iSockApi Data Structures

Structure Description

iIPAddr Represents an IP address; facilitatesaccess to the 32-bit value or theindividual bytes.

iSockInfo Includes all data necessary to defineone side of a connection (IPaddr, port).



IsInitSocket

This function initializes software components.

Prototype RET_CODE IsInitSocket()

Input(s) None

Output(s) None

Returns RET_CODE_OK

Blocking No


IsTCPConnect

This function attempts to open a TCP connection to the specified host (IP address)on the specified port.

Prototype RET_CODE IsTCPConnect(iTCPId *id, iIPAddr ip,iPort portNum, iTimeout tmo)

Input(s) id: The id value is valid to use in IsTCPRead, IsTCPWrite or IsTCPClose after a successful execution of this function.

ip: Destination IP address.

portNum: Destination port.


Output(s) id: A handle for the connected socket, type iTCPId, that is returned when a successful connection is established.

Returns RET_CODE_OK

RET_CODE_ABORT

ISRC_NO_AVAILABLE_SOCKET

ISRC_TIMEOUT

ISRC_TERMINATED

ISRC_RESET

Blocking Yes



isTCPConnect (con't)

IsTCPListen

This function is called when an application wants to listen to a specified port andaccept a TCP connection. It waits until a connection is accepted or the attempt fails(including timeout). If a client attempts to connect to the device, the connection isaccepted and the function returns the connected socket.

Prototype RET_CODE IsTCPListen (iTCPId *id, iPort portNum,iTimeout tmo)

Input(s) id: The id value is valid to use in IsTCPRead, IsTCPWrite or IsTCPClose after a successful execution of this function.

portNum: Port number for listening.


Output(s) id: iTCPId that is returned when a successful connection is accepted.

Returns RET_CODE_OK

RET_CODE_ABORT


ISRC_TIMEOUT

ISRC_TERMINATED

ISRC_RESET

Blocking Yes


Example:#include <iSockApi.h>

iIPAddr ip; /* destination host ip address */iPort portNum = 8041; /* port number */RET_CODE rc = RET_CODE_OK;iTCPId sockId = 0; /* socket handle */iTimeout tmo = ITMO_INFINITE;

/* setting IP address of "192.168.8.1" */ip.ipb1 = 192; /*the most significant byte of ip address*/ip.ipb2 = 168;ip.ipb3 = 8;ip.ipb4 = 1; /*the least significant byte of ip address*/

rc = IsTCPConnect (&id, ip, portNum, tmo);if (rc != RET_CODE_OK) {

/* handle error */}



IsTCPRead

This function reads data from an active TCP socket. When data is not available, itwaits; when data is available, it reads all of the data (not more than the buffer size)into the buffer and returns a RET_CODE_OK. The len value at call time is thebuffer size, and at return time, if the returned value is RET_CODE_OK, is thenumber of bytes read.

Prototype RET_CODE IsTCPRead(iTCPId id, iDataBuf buffer,iDataLen *len, iTimeout tmo)

Input(s) id: TCP socket handle.

buffer: Pointer to a buffer for incoming data.

len: Buffer size in bytes.

tmo: Timeout value (in 10ms units). ITMO_INFINITE can be used for no timeout. ITMO_NO_RETRY can be used to try only once then return.

Output(s) buffer: Contains the data read.

len: Number of bytes actually read.

Returns RET_CODE_OK

RET_CODE_ABORT

ISRC_SOCKET_CLOSING

ISRC_NOT_CONNECTED

ISRC_TERMINATED

ISRC_RESETED

ISRC_BAD_SOCKET_ID

Blocking Yes


NOTE: Remember to set the len parameter before every IsTCPRead call, otherwise one shortread will lower the len parameter and application performance will be impaired. Refer toline 33 in the Sample Code at the end of this chapter.



IsTCPWrite

This function attempts to write data through a connected TCP socket. The functionblocks until all of the data is transferred to the socket or until the attempt fails.

Prototype RET_CODE IsTCPWrite(iTCPId id, iDataBuf buffer,iDataLen len, iTimeout tmo)


buffer: Pointer to the data to be sent.

len: Length of data to be sent.

tmo: Timeout value (in 10ms units). ITMO_INFINITE can be used for no timeout. ITMO_NO_RETRY can be used to try only once then return.

Output(s) None

Returns RET_CODE_OK

RET_CODE_ABORT

ISRC_NOT_WRITABLE

ISRC_TIMEOUT

ISRC_BAD_SOCKET_ID

Blocking Yes


IsTCPClose

This function closes the TCP socket indicated by the socket handle.

Prototype RET_CODE IsTCPClose(iTCPId id, iTimeout tmo)

Input(s) id: TCP socket handle. The id is invalid after the execution of this function.


Output(s) None

Returns RET_CODE_OK

ISRC_NOT_CONNECTED

ISRC_BAD_SOCKET_ID

Blocking Yes




IsTCPAbort

The purpose of this function is to unblock and abort an operation executed with thesocket. This function can be used in an interrupt.

Prototype RET_CODE IsTCPAbort(iTCPId id)


Output(s) None

Returns RET_CODE_OK

ISRC_BAD_SOCKET_ID

Blocking No

IsUDPCreate

This function opens a UDP socket.

Prototype RET_CODE IsUDPCreate(iUDPId *id, iPort portNum)

Inputs portNum: Port number for listening

Output(s) id: The UDP ID of a socket that was successfully opened.

Return(s) RET_CODE_OK


Blocking Yes


iPORT portNum = 8041; /* port number */RET_CODE rc = RET_CODE_OK;iUDPId id; /* socket handle */

rc = IsUDPCreate (&id, portNum);if(rc != RET_CODE_OK) {

/* handle error */}



IsUDPRead

This function attempts to read a UDP packet.

Prototype RET_CODE IsUDPRead (iUDPId id, iSockInfo *from,iDataBuf buffer, iDataLen *len, iTimeout tmo)

Input(s) id: UDP socket handle.

buffer: Pointer to a buffer for incoming data.

len: Buffer size.

tmo: Timeout value (in 10ms units). ITMO_INFINITE can be used for no timeout. ITMO_NO_RETRY can be used to try only once and then return.

Output(s) buffer: Actual data read.

from: Packet sender’s information in the iSockInfo structure.

len: UDP packet size.

Returns RET_CODE_OK

RET_CODE_ABORT

ISRC_NOT_ACTIVATED

ISRC_NOT_CONNECTED

ISRC_TERMINATED

ISRC_RESET

ISRC_UDP_TOO_MUCH_DATA

Blocking Yes

Example:#include <iSockApi.h>#define MAXLEN 1024

RET_CODE rc = RET_CODE_OK;iSockInfo from;iUDPId id;iDataBuf buffer [MAXLEN];iDataLen len = MAXLEN;iTimeout tmo = ITMO_INFINITE;

/* invoke IsUDPCreate(&id,…) */

rc = IsUDPRead(id, &from, buffer, &len, tmo);if(rc != RET_CODE_OK) {

/* handle error */}



IsUDPWrite

This function writes a packet of data through the UDP socket.

Prototype RET_CODE IsUDPWrite(iUDPId id, iSockInfo *dest,iDataBuf buffer, iDataLen len, iTimeout tmo)


dest: A structure that contains the destination IP address and port number.

buffer: Pointer to the data to be sent.

len: Length of the data to be sent.


Output(s) None

Returns RET_CODE_OK

ISRC_UDP_TOO_MUCH_DATA

ISRC_TIMEOUT

ISRC_TERMINATED

ISRC_RESET

Blocking Yes


iPORT portNum = 8041;RET_CODE rc = RET_CODE_OK;iTCPId id;iDataBuf buffer = " The quick fox jumped over the lazy brown dog ";iDataLen len = 50;iTimeout tmo = ITMO_INFINITE;iSockInfo dest;

/* invoke IsUDPCreate(&id,…) */

rc = IsUDPWrite (id, dest, buffer, len, tmo);if(rc != RET_CODE_OK) {

/* handle error */}



IsUDPRelease

This function releases the UDP socket that is indicated by the socket handle.

Prototype RET_CODE IsUDPRelease(iUDPId id, iTimeout tmo)

Input(s) id: UDP socket handle—after this function is executed, the id is invalid.


Output(s) None

Returns RET_CODE_OK

Blocking Yes

IsUDPAbort

This function unblocks and aborts an operation executed by the socket.

Prototype RET_CODE IsUDPAbort(iUDPId id)


Output(s) None

Returns RET_CODE_OK

ISRC_BAD_SOCKET_ID

Blocking Yes


RET_CODE rc = RET_CODE_OK;iUDPId id;

rc = IsUDPRelease(id);if(rc != RET_CODE_OK) {

/* handle error */}




/* echo server task */

#include <iReady.h>#include <iStacApi.h> /* isPPPcheck */#include <iSockApi.h>#include <iSys.h>

#define BUF_LEN 120#define A_LONG_TIME 10000#define A_WHILE 100

void echo(void *data) {RET_CODE rc;iTCPId sockId = 0;iDataLen len;char buf[BUF_LEN];iSockInfo info;iPort thePort = (iPort)data;

while(RET_CODE_OK != IsPPPCheck(0))smallSleep(A_WHILE);

rc = IsInitSocket();if(RET_CODE_OK == rc) {for(;;) {

rc = IsTCPListen(&sockId, &info, thePort, ITMO_INFINITE);if(RET_CODE_OK != rc) {

smallSleep(A_WHILE);continue;}

while(RET_CODE_OK == rc) {len = BUF_LEN;rc = IsTCPRead(sockId, (iDataBuf)buf, &len, A_LONG_TIME);if(RET_CODE_OK == rc)

rc = IsTCPWrite(sockId, (iDataBuf)buf, len, A_WHILE);}

IsTCPClose(sockId);}

}}

5

10

15

20

25

30

35

40

Itask FunctionsThis chapter is a guide to each of the ItaskApi functions, including parametersand data structures.

Chapter

4



OverviewThe Itask kernel is simple. It allows one main task with callback tasks for performingperiodic activities. The main task could be written largely unaware that it is the maintask in a single task kernel. It performs its system activities and blocks when it needsthings.

When this main task blocks, the callback functions are executed. The callbackfunctions are expected to not block. If they need data, they can use theITMO_NO_RETRY timeout setting to ensure they do not block. If the callback has toperform some time-consuming calculation, it should do only a small part each time it iscalled.

Callbacks are usually state-based. The development process usually starts with a statediagram describing what this task will do. This diagram is then translated into a switchstatement (or similar functionality) in the callback task. The main task then sets thestate to the initial state before adding the callback via ItaskCbAdd.

Tunable Parameters

The tunable parameters for Itask are listed below. The parameters are defined atcompilation time.

MAX_CALLBACKS

Maximum number of callbacks, default: 3

Callback system code will not be included if: 0

MAX_TCALLBACKS

Maximum number of timer callbacks, default: 1

Timer callback system code will be not included if: 0

I T A S K F U N C T I O N S

4-4-33 iReady Network Stack Driver APIsiReady Network Stack Driver APIs

Itask Functions

The ItaskAPI functions provide an interface to the iReady Mini-task kernel. Table 4-1contains an overview of the functions.

Table 4-1 Itask API Function Overview


ItaskInit This function initializes the Itask kernel.

ItaskCbAdd Adds a function to be executed as acallback.

ItaskCbRemove Removes a function previously registeredby ItaskCbAdd from the list of functions tobe called by the Itask kernel.

ItaskTcbAdd Adds a function to be executed at specifictimer intervals.

ItaskTcbRemove Removes a function previously registeredby ItaskTcbAdd from the list of functions tobe called by the Itask kernel.

ItaskCallback Calls each of the callback routines oncewhen called.

ItaskTicCnt Returns the current tick count.

Table 4-2 contains the return code values that specify possible return conditions in Itaskoperations.

Table 4-2 ItaskAPI Return Codes



IT_ALREADY_INITIALIZED Itask is already initialized.

IT_NO_SUPPORT Requested operation is notsupported.

IT_TASK_ID_INVALID Callback identifier is no longervalid.

IT_CODE_MAX_TASKS_ALLOCATED Number of maximum tasksallocated has been exceeded.



ItaskInit

This function initializes the Itask kernel. It must be called before any other Itaskfunctions can be used.

Prototype RET_CODE ItaskInit()

Inputs None

Outputs None

Returns RET_CODE_OK

IT_ALREADY_INITIALIZED

Blocking No


ItaskCbAdd

This function adds a function to be executed as a callback. The Itask kernel calls thefunction with the parameter (call_ptr) as shown in the function prototype.

If more than one function has been added with this function, the Itask kernel willexecute the function with the higher registered priority number first. The functionpassed should return a U16. If it returns a non-zero value, the Itask kernel will notexecute any lower priority functions during the current task execution cycle and passescontrol back to the last blocking task.

Prototype RET_CODE ItaskCbAdd(iCBid *id, U16 priority,iCB_FUNC function, void *call_ptr)

Inputs priority: Priority of the function, higher priority functions get executed first.

function: Pointer to the function to be called by the Itask kernel.

call_ptr: Optional parameter used to call the function. Set to NULL if no parameter is desired.

Outputs id: Callback task identifier.

Returns RET_CODE_OK

IT_MAX_TASKS_ALLOCATED

IT_NO_SUPPORT

Blocking No

Example Reference lines 61 & 62 in the Sample Code at the end of this chapter.



ItaskCbRemove

This function removes a function previously registered by ItaskCbAdd from the list offunctions to be called by the Itask kernel.

Prototype RET_CODE ItaskCbRemove(iCBid id)

Inputs id: Callback identifier of a task previously allocated by ItaskCbAdd.

Outputs None

Returns RET_CODE_OK

IT_TASK_ID_INVALID

Blocking No


ItaskTcbAdd

This function adds a function to be executed at specific timer intervals. The Itaskkernel will call the function with the parameter call_ptr. The function passed shouldreturn a U16; if it returns a non-zero value, the Itask kernel will automatically removethe task. The next timer check will not encounter this callback.

Prototype RET_CODE ItaskTcbAdd(iTCBid *id, U16 period,iCB_FUNC function, void *call_ptr)

Inputs period: Frequency (in ms) that executes the callback.

function: Pointer to the function to be called by the Itask kernel.

call_ptr: Optional parameter used to call the function, set to NULL if no parameter is desired.

Outputs id: Timer callback task identifier

Returns RET_CODE_OK

IT_NO_SUPPORT

IT_MAX_TASKS_ALLOCATED

Blocking No




ItaskTcbRemove

This function removes a function previously registered by ItaskTcbAdd from the list offunctions to be called by the Itask kernel.

Prototype RET_CODE ItaskTcbRemove(iTCBid id)

Inputs id: Callback identifier of a task previously allocated by ItaskTcbAdd.

Outputs None

Returns RET_CODE_OK

IT_TASK_ID_INVALID

Blocking No

ItaskCallback

This function calls each of the callback routines once when called.

Prototype void ItaskCallback()

Inputs None

Outputs None

Returns None

Blocking No


Example:main(){

RET_CODE ret;iTCBid timertask;

…/* call the task ‘serial’ every 200 timer ticks */ret = ItaskTcbAdd(&timertask, 200, serial, NULL);…/* remove the previously defined timertask */ret = ItaskTcbRemove(timertask);…



ItaskTicCnt

This function returns the current tick count.

Prototype U16 ItaskTicCnt()

Inputs None

Outputs None

Returns None

Blocking No

Example None




/* Itask Example Program */

#include "itask.h"#define MAX_EVENTS 10000#define TIMEOUT 30000int event_flag = 0;

/* keyboard task, checks for keyboard action and adds any key hits to abuffer

*/U16 keyboard() {

char key;/* check for keyboard hit */if(inport(0x130) & 0x1){

key = inport(0x131);addkey2buffer(key);

}return(0);

}

/* serial out task, called every 100 clock ticks */

U16 serial() {char data;/* write queued data to serial port */while(data = getqueuedchar()){

outport(data);}

return(0);}

/* this task counts the number of times the device on port 0x200 has beentriggered*/

U16 trigger_event() {/* check if event has been triggered */if(inport(0x200) & 0x1){

/* reset trigger to catch next event */outport(0x200) = 0;

/* notify main task of this event */event_flag = 1;

}return(0);

}

main() {iCBid task1,task2;iTCBid timertask;int end = 0;/* initialize Itask */ItaskInit();

/* add keyboard and trigger event tasks to be called as much aspossible */ItaskCbAdd(&task1,1, keyboard, NULL);ItaskCbAdd(&task2,3, trigger_event, NULL);

/* add the serial task to send data every 100 clock ticks */ItaskTcbAdd(timertask, 100, serial, NULL);

5

10

15

20

25

30

35

40

45

50

55

60

65



/* main loop */while(end!= 1){

U16 starttick = 0;

/* wait for keypress or traffic event or timeout */starttick=ItaskTicCnt();while(((key=getkeyfrombuffer())==0) && (event_flag==0)) &&

((ItaskTicCnt()-startick) < TIMEOUT))ItaskCallback();

/* check for timeout, if keyboard or event didn't happen in *//* TIMEOUT ticks then exit program */if(ItaskTicCnt()-startick) < TIMEOUT){

end = 1;continue;

}

/* check if there is a key, if so queue it to be sent */if(key!=0)

{queuechar(key);}

/* check if there was an event */if(event_flag){

event_count+= 1;event_flag = 0;

/* queue a '+' character to signify an event happened */queuechar('+');

/* if MAX_EVENTS have happened, stop the trigger_eventtask and stop counting events */if(event_count>MAX_EVENTS){

ItaskCbRemove(task2);}

} }

}

70

75

80

85

90

95

100

105

110

Building and Porting Instructions

Chapter

5


iReady CorporationiReady Corporation 55--66 Confidential and ProprietaryConfidential and Proprietary

OverviewCurrently, the iReady driver is portable to ITRON 3.0, NORTi, and microC/OSoperating systems under several platforms. The iReady API is independent from anyRTOS because the iSys encapsulates the OS dependent implementation from the driver.Therefore, users do not need to be familiar with iSys (refer to Chapter 1 for more iSysdetails).

The target RTOS must be specified at library building time in order to use the iReadydriver with currently supported RTOS's. The iReady driver library can be generated byusing the iReady-provided common build system.

Library Build InstructionThe build tools are completely separate from the compilation tools. A GNU make isused because it is freely available and widely adopted. A windows binary for make isincluded in this release.

The GNU make program is used to control the invocation of the various tools requiredto build the tree. It is also responsible for controlling the make dependencies betweenvarious modules of the tree.

The values in Table 5-1 should be set prior to compilation if the default values are notappropriate for local environmental settings.

Table 5-1 Settings

Variable Default Other acceptable values

HOST Win32 <none>

HOSTVSN <none> J (for Japanese Windowssystem)

TOOLS TOOLS_MS16 H8

CPU X86 H8S, Z80, Z180

CPUID <none> 2000, 2600, Pent

HWIFACE MEMMAP IOMAP

ITARGOS ITARGOS_uCos ITRON, NORTi

IBUS IBUS_ISA PC104, EMBEDDED, Z104

COM_DEV COM_DEV_MODEM NULLMDM, MAC

COM_MODE COM_MODE_SERIAL PARALLEL

ICLOCK_FREQ 1000000

SUBCOMP_STAC SUBCOMP_HARDWARE

SUBCOMP_SOCK SUBCOMP_HARDWARE



The following values are dependent on the tool set (TOOLS variable):

TOOLBASE Path to the C compiler (i.e. c:/msvc15)

ASMBASE Path to the assembler (i.e. c:/masm)

The following value is dependent on the OS selection:

SYSBASE Path to base of operating system (i.e. c:/uCOS)

The make program needs the appropriate values of these variables when it is executed.Examples of supported value combinations are indicated in the go.bat file—forexample, go 20 will build the uCos/x86 configuration. See the go.bat file for moreinformation.

BuildsBuilds on a particular system can be made to default to the appropriate configuration forthat system. This is possible by creating a new section in the go.bat file or by setting theappropriate variables in the AUTOEXEC.BAT and using "make –e". These can beadded to the AUTOEXEC.bat file to set each time the system boots. See the examplebelow:

rem The following lines tell make to use these values as default

rem values. These are appropriate for the NORTi/H8 system.

set MAKEFLAGS=-e

set TOOLS=TOOLS_MS16

set CPU=x86

set CPUID=Pent

set HWIFACE=IOMAP

set IBUS=IBUS_ISA

set COM_DEV=COM_DEV_MODEM

set COM_MODE=COM_MODE_SERIAL

set TARGOS=TARGOS_uCos

set SYSBASE= ../system/uCos

set ICLOCK_FREQ=10000000

P O R T I N G T O O T H E R R T O S ' S

55--77 iReady Network Stack Driver APIsiReady Network Stack Driver APIs

At the top level there are five files used for building the tree:

makefile

mktools/mkconf

mktools/mktarg

mktools/mytarg

mktools/mylocal

For building the tree, these are the only files required. For further softwaredevelopment in the tree, continue reading this section for information on how the makemechanism is used in the tree.

The makefile is the master make for the entire tree, but it includes most of itsfunctionality from the other files. Therefore, to call the new build process, change tothis directory and type make. This will include configuration information from themkconf file.

The mkconf file is designed to abstract the tool and environment information. By doingso, the module make files do not need the details for building on various supported hostconfigurations and various target platforms using various tool sets.

After the tools are included, the make begins including rule information throughout thetree. This rule information provides the instructions for building the entire tree. Ineffect, this is an inclusive make mechanism first proposed by Peter Miller. Visithttp://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html for moreinformation on this approach.

Each branch level makefile simply includes the makefiles from the subdirectories itknows about. Each leaf level makefile includes mylocal, which resets certain values toensure that settings are not inherited from the previous directory.

The leaf makefile then defines some variables particular to the module beingconstructed, and includes rules from the mytarg file. This instantiates rules for thisparticular part of the tree.

After all the tree rule information is included, the master makefile includes mktarg. Thisdefines final targets and rules for those things that use the default constructiontechniques.

The makefiles support the following targets:

all Build all targets

install Build targets and populate public directories (i.e. include, lib, and bin)

clean Remove object files created during compilation

realclean Remove object files and result binaries

In addition, the user may request a particular file to be built. This can be accomplishedby giving the path to the file as the target (e.g make drv/mail/imail.obj).

Specific branches can also be cleaned via the following mechanism:

make CLEANS=drv/mail/*.obj clean

Exercise care when using this mechanism because there is no check to ensure that thesource files are being cleaned out!



Troubleshooting Tips

1. If the version of the CC compiler changes in the H8 system, the mkconf file needsto be changed or the builder must set:

CCBASE=$(TOOLBASE)/Ch38/Vxxx

in its own environment.

2. If the reserved environment space is not large enough for the Windows system, amessage, “out of environmental space”, will occur when go.bat is executed. If thisoccurs the environment space needs to be increased via the following line inCONFIG.SYS:

SHELL=c:\command.com c:\ /P /E:4096

Change the /E:xxxx value to a larger size (e.g. increase the value to 8192).

Note: A disadvantage of residing on command.com is that it periodically crashes.

3. Redirecting the build output can cause problems. Use a redirector program such asredir.pl in the mktools directory as a work-around.

The redirection script in the mktools directory may be used as follows:

perl mktools\redir.pl make.out perl go 4

4. The iReady build system is subject to limitations because it resides on top of MS-DOS. For example, if an attempt is made to redirect the output of the go.bat scriptthe build may fail to complete. The output file producing the final line will be

C:\>

If this happens, the build will have to be executed without the redirection.

5. Problems with the MKSNT tool set: It is advisable to remove the MKSNT toolsfrom the path in the window where the make or go scripts are executed. If theMKSNT tool set is used, remove them from the path in the DOS window where thebuild for the iReady build system is executed. If not, an error that “echo” syntax isincorrect will most likely occur.

P O R T I N G T O O T H E R R T O S ' S

55--77 iReady Network Stack Driver APIsiReady Network Stack Driver APIs

Application Build Environment

Building an application with the iReady APIs under a specified RTOS requires theapplication, API libraries and RTOS library to be linked together. Although users maywant to use their own build system, a general build environment is illustrated in Figure5-1.

Figure 5-1 Build Environment Diagram

Porting to another RTOSThis section explains the porting procedure that replaces the current RTOS with anotherRTOS. However, this is not yet supported by iReady. To build the API library for thenew RTOS, the minimum number of required tasks include:

1. Users can write their own product\sys\<RTOS dir>\iSys.c for the new RTOS. Theinterface specification must follow the function prototypes specified inproduct\include\iSys.h.

2. Modify the product\makefile and product\mktools\mkconf files to support thecompilation and link requirements for the new RTOS. The required modification touse depends on the RTOS.

3. Add the section in the go.bat file to support the modification of the build system.

Application Source Code

RTOS Library

Application Executable

Application Object

iReady API LibraryiDrvUtil.lib iSys.libistac.lib isock.lib

Compiler

Linker

Appendix

A

A P P E N D I X A N e t w o r k S t a c k D r i v e r

iReady CorporationiReady Corporation A-A-22 Confidential and ProprietaryConfidential and Proprietary

iSys.h

#ifndef ISYS_H#define ISYS_H

#include <iReady.h>

/* generic synchronization mechanism */#define iSYS_SYNCH_SIZE sizeof(void*)RET_CODE iSysInit(void*);RET_CODE iSysPend(void*, iTimeout);RET_CODE iSysAbort(void*);RET_CODE iSysPost(void*);

typedef union {VOID *V;CHAR C[ISYS_SYNCH_SIZE];} ISPPTYPE; /* SYNCH PRIMITIVE PLACEHOLDER TYPE */

void smallSleep(iTimeout);

#ifndef iSYS_TIME_SIZE#define iSYS_TIME_SIZE sizeof(long)#endif

typedef union {ITIMEOUT T;CHAR C[ISYS_TIME_SIZE];} ISTSSTYPE; /* SYSTEM TIME SIZE SAMPLE TYPE */

RET_CODE iSysGetTime(iSTSSType*);iTimeout iSysDiffTime(iSTSSType*);

#endif

Appendix

B

A P P E N D I X B N e t w o r k S t a c k D r i v e r

iReady CorporationiReady Corporation B-B-22 Confidential and ProprietaryConfidential and Proprietary

iSys.c (uCos)

#include <UCOSinc.h>#include <iSys.h>

#ifndef MS_PER_TICK#define MS_PER_TICK 55 /* 18.2 per second */#endif

typedef struct_iSYS_SYNCH {UBYTE prio, abrt;} iSYS_SYNCH;

RET_CODEiSysInit(void *issp) {

OS_ENTER_CRITICAL();((iSYS_SYNCH*)issp) ->prio = OS_PRIO_SELF; /* 0xFF */((ISYS_SYNCH*)ISSP) ->ABRT = 0;OS_EXIT_CRITICAL();return RET_CODE_OK;

}

RET_CODEiSysAbort(void *issp) {

OS_ENTER_CRITICAL();((iSYS_SYNCH*)issp) ->abrt = 1;OSTimeDlyResume( ((iSYS_SYNCH*)issp) ->prio);OS_EXIT_CRITICAL();return RET_CODE_OK;

}

RET_CODEiSysPost(void *issp) {

OSTimeDlyResume( ((iSYS_SYNCH*)issp) ->prio);return RET_CODE_OK;

}

RET_CODEiSysPend(void *issp, iTimeout to) {

RET_CODE rc = RET_CODE_OK;UWORD tics = (to + MS_PER_TICK – 1) / MS_PER_TICK;

((iSYS_SYNCH*)issp) ->prio = OSTCBCur->OSTCBPrio;

OSTimeDly(tics);

OS_ENTER_CRITICAL();((iSYS_SYNCH*)issp) ->prio = OS_PRIO_SELF; /* 0xFF */if( ((iSYS_SYNCH*)issp) ->abrt) {

rc = RET_CODE_ABORT;((iSYS_SYNCH*)issp) ->abrt = 0;}

OS_EXIT_CRITICAL();return rc;

}

void smallSleep(iTimeout ms) {UWORD tics = (MS_PER_TICK – 1 + ms) /MS_PER_TICK;OSTimeDly(tics);

}

RET_CODE iSysGetTime(iSTSSType *t) {t->t = (iTimeout)OSTimeGet();return RET_CODE_OK;

}


B-B-33 iReady Network Stack DriveiReady Network Stack Driver APIsr APIs

iSys.c (uCos) con't

iSys.C (NORTi)

U16 iSysDiffTime(iSTSSType *t) {return((OSTimeGet() – t->t) * MS_PER_TICK) /10;

}

#include <norti.h>#include <iSys.h>

typedef struct _iSYS_SYNCH {ID tid;} iSYS_SYNCH;


((iSYS_SYNCH*)issp)->tid = TSK_SELF; /* 0 */}

RET_CODEiSysAbort(void *issp) {

rel_wai( ((iSYS_SYNCH*)issp)->tid );}


if(TSK_SELF != ((iSYS_SYNCH*)issp)->tid )iwup_tsk( ((iSYS_SYNCH*)issp)->tid );

}


ER ercd = get_tid( &(((iSYS_SYNCH*)issp)->tid) );ercd = wai_tsk(to);((iSYS_SYNCH*)issp)->tid = TSK_SELF; /* 0 */return (E_RLWAI == ercd) ? RET_CODE_ABORT : RET_CODE_OK;

}

void smallSleep(iTimeout ms) {int tim = (0 == ms) ? MSEC : (ms – 1 + MSEC);wai_tsk(tim / MSEC); /* round up */

}

RET_CODE iSysGetTime(iSTSSType *t) {T_TIME now;get_tim(&now);t->t = (iTimeout) (now.ltime);return RET_CODE_OK;

}

U16 iSysDiffTime(iSTSSType *t) {iTimeout now;get_tim(&now);return ( (now.ltime) – t->t ) * MSEC ) /10;

}

A P P E N D I X B

iReady CorporationiReady Corporation B-B-44 Confidential and ProprietaryConfidential and Proprietary

iSys.C (iTRON)

#include <iTypes.h>#include <iSys.h>#include <iTron.h>#include <itron_errno.h>#include >itis_debug.h>#include >itis_isyscall.h>#define MSEC 1

typedef struct _iSYS_SYNCH {ID tid;} iSYS_SYNCH;


((iSYS_SYNCH*)issp)->tid = TSK_SELF; /* 0 */}

RET_CODEisysAbort(void *issp) {

rel_wai( ((iSYS_SYNCH*)issp)->tid );}


if(TSK_SELF != ((iSYS_SYNCH*)issp)->tid )wup_tsk( ((iSYS_SYNCH*)issp)->tid );

}


ER ercd = get_tid( &(((iSYS_SYNCH*)issp)->tid) );ercd = tslp_tsk(to);((iSYS_SYNCH*)issp)->tid = TSK_SELF; /* 0 */return (E_RLWAI == ercd) ? RET_CODE_ABORT : RET_CODE_OK;

}

void smallSleep(iTimeout ms) {int tim = (0 == ms) ? MSEC : (ms – 1 + MSEC);tslp_tsk( tim / MSEC ); /* round up */

}

RET_CODE iSysGetTime( iSTSSType *t ) {get_tim( (SYSTIME*)t 0 {return RET_CODE_OK;

}

U16 iSysDiffTime( iSTSSType *t ) {SYSTIME t0;get_tim( &t0 );return (iTimeout)( *(SYSTIME*)&t0 - *(SYSTIME*)t );

}

softwa re developmen t kit s-7600abooks.mhprofessional.com/engineering/updatezone/... · s-7600a...

Documents