net/tcp.h File Reference


Detailed Description

TCP Module for Modtronix TCP/IP Stack.

Author:
Modtronix Engineering
Dependencies:
stacktsk.h
Compiler:
MPLAB C18 v2.10 or higher
HITECH PICC-18 V8.35PL3 or higher

Description

This module contains the TCP code.
For a detailed description, see the TCP section of this document - in [Modules] [TCP/IP Stack] [TCP/IP Base Protocols].

Configuration

The following defines are used to configure this module, and should be placed in the projdefs.h (or similar) file. For details, see Project Configuration. To configure the module, the required defines should be uncommended, and the rest commented out.
 //*********************************************************************
 //-------------------- TCP Configuration --------------------
 //*********************************************************************
 //Maximum number of times a connection be retried before closing it down.
 #define TCP_MAX_RETRY_COUNTS    (3)

 //TCP Timeout value to begin with. This value should normally be from 250ms to 5 seconds
 #define TCP_START_TIMEOUT_VAL_1   ((TICK16) (TICKS_PER_SECOND * 2))

 //Define ports
 #define TCP_LOCAL_PORT_START_NUMBER (1024)
 #define TCP_LOCAL_PORT_END_NUMBER   (5000)

 //When defined, the code will be compiled for optimal speed. If not defined, code
 //is defined for smallest size.
 #define TCP_SPEED_OPTIMIZE

 //When defined, each TCP segment is sent twice. This might cause the remote node to
 //think that we timed out and retransmitted. It could thus immediately send back an
 //ACK and dramatically improve throuput.
 #define TCP_SEND_EACH_SEGMENT_TWICE

#include "net\ip.h"
#include "net\tick.h"

Data Structures

struct  _SOCKET_INFO

Defines

#define INVALID_SOCKET   (0xfe)
#define REMOTE_HOST(s)   (TCB[s].remote)
#define SIZEOF_MAC_HEADER   14
#define TCP_LOCAL_PORT_END_NUMBER   (5000)
#define TCP_LOCAL_PORT_START_NUMBER   (1024)
#define TCP_MAX_RETRY_COUNTS   (3)
#define TCP_START_TIMEOUT_VAL_1   ((TICK16) (TICKS_PER_SECOND * 2))
#define TCPGetMaxDataLength()   (MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(TCP_HEADER))
#define UNKNOWN_SOCKET   (0xff)

Typedefs

typedef _SOCKET_INFO SOCKET_INFO
typedef WORD TCP_PORT
typedef BYTE TCP_SOCKET
typedef enum _TCP_STATE TCP_STATE

Enumerations

enum  _TCP_STATE {
  TCP_LISTEN = 0, TCP_SYN_SENT, TCP_SYN_RECEIVED, TCP_ESTABLISHED,
  TCP_FIN_WAIT_1, TCP_FIN_WAIT_2, TCP_CLOSING, TCP_TIME_WAIT,
  TCP_CLOSE_WAIT, TCP_LAST_ACK, TCP_CLOSED
}

Functions

TCP_SOCKET TCPConnect (NODE_INFO *remote, TCP_PORT remotePort)
BOOL TCPDiscard (TCP_SOCKET s)
void TCPDisconnect (TCP_SOCKET s)
BOOL TCPFlush (TCP_SOCKET s)
BOOL TCPGet (TCP_SOCKET s, BYTE *byte)
WORD TCPGetArray (TCP_SOCKET s, BYTE *buffer, WORD count)
SOCKET_INFOTCPGetSocketInfo (TCP_SOCKET s)
void TCPInit (void)
BOOL TCPIsConnected (TCP_SOCKET s)
BOOL TCPIsGetReady (TCP_SOCKET s)
BOOL TCPIsPutReady (TCP_SOCKET s)
TCP_SOCKET TCPListen (TCP_PORT port)
BOOL TCPProcess (NODE_INFO *remote, IP_ADDR *localIP, WORD len)
BOOL TCPPut (TCP_SOCKET s, BYTE byte)
BOOL TCPPutArray (TCP_SOCKET s, BYTE *buffer, WORD count)
void TCPTick (void)

Variables

SOCKET_INFO TCB [MAX_SOCKETS]


Define Documentation

#define INVALID_SOCKET   (0xfe)

Examples:
ex_tcp.c, ex_tcp_client.c, and ex_tcp_echo.c.

#define REMOTE_HOST (  )     (TCB[s].remote)

#define SIZEOF_MAC_HEADER   14

Returns the maximum size the TCP data is allowed to be. This value should never be execeed when writting data to the TCP transmit buffer before calling TCPFlush(). For slip: = MAC_TX_BUFFER_SIZE - sizeof(IP_HEADER) - sizeof(TCP_HEADER) = MAC_TX_BUFFER_SIZE - 20 - 20 = MAC_TX_BUFFER_SIZE - 40 For RTL MAC = MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(TCP_HEADER) = MAC_TX_BUFFER_SIZE - 14 - 20 - 20 = MAC_TX_BUFFER_SIZE - 54

#define TCP_LOCAL_PORT_END_NUMBER   (5000)

#define TCP_LOCAL_PORT_START_NUMBER   (1024)

#define TCP_MAX_RETRY_COUNTS   (3)

Maximum number of times a connection be retried before closing it down.

#define TCP_START_TIMEOUT_VAL_1   ((TICK16) (TICKS_PER_SECOND * 2))

TCP Timeout value to begin with.

 
#define TCPGetMaxDataLength (  )     (MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(TCP_HEADER))

#define UNKNOWN_SOCKET   (0xff)


Typedef Documentation

typedef struct _SOCKET_INFO SOCKET_INFO

Socket info. Union is used to create anonymous structure members.

typedef WORD TCP_PORT

A TCP PORT. Is a number from 0-65536 that identifies a TCP port

typedef BYTE TCP_SOCKET

A TCP socket. Is a number from 0-255 that identifies a TCP socket

Examples:
ex_tcp.c, ex_tcp_client.c, and ex_tcp_echo.c.

typedef enum _TCP_STATE TCP_STATE

TCP States as defined by rfc793


Enumeration Type Documentation

enum _TCP_STATE

TCP States as defined by rfc793

Enumerator:
TCP_LISTEN 
TCP_SYN_SENT 
TCP_SYN_RECEIVED 
TCP_ESTABLISHED 
TCP_FIN_WAIT_1 
TCP_FIN_WAIT_2 
TCP_CLOSING 
TCP_TIME_WAIT 
TCP_CLOSE_WAIT 
TCP_LAST_ACK 
TCP_CLOSED 


Function Documentation

TCP_SOCKET TCPConnect ( NODE_INFO remote,
TCP_PORT  remotePort 
)

Do an TCP active open. By default this function is not included in source. You must define STACK_CLIENT_MODE to be able to use this function.

After calling this function, the TCP stack will try and connect with the given target. The user should call the TCPIsConnected() function to see if the connection has been made. The TCP stack will continuously try and connect. It is up to the user to terminate the connection attempts if no connection is made after a certian time. The TCPDisconnect() function can be used to stop the TCP stack from trying to connect.

Pre-Condition:
TCPInit() is already called.
Parameters:
remote Remote node address info
remotePort remote port to be connected.
Returns:
A new socket is created, connection request is sent and socket handle is returned.
Examples:
ex_tcp_client.c.

BOOL TCPDiscard ( TCP_SOCKET  s  ) 

Discard any data contained in the given socket's receive buffer.

Pre-Condition:
TCPInit() is already called.
Parameters:
s socket
Returns:
TRUE if socket received data was discarded
FALSE if socket received data was already discarded
Examples:
ex_tcp.c, and ex_tcp_echo.c.

void TCPDisconnect ( TCP_SOCKET  s  ) 

A disconnect request is sent for given socket.

Pre-Condition:
TCPInit() is already called AND
TCPIsPutReady(s) == TRUE
Parameters:
s Socket to be disconnected.
Examples:
ex_tcp_client.c.

BOOL TCPFlush ( TCP_SOCKET  s  ) 

All and any data associated with this socket is marked as ready for transmission.

Pre-Condition:
TCPInit() is already called.
Parameters:
s Socket whose data is to be transmitted.
Returns:
TRUE is action was performed
FALSE if not
Examples:
ex_tcp_client.c, and ex_tcp_echo.c.

BOOL TCPGet ( TCP_SOCKET  s,
BYTE byte 
)

This function reads the next byte from the current TCP packet. Reads a single byte from the given socket into the given byte pointer

Pre-Condition:
TCPInit() is already called AND TCPIsGetReady(s) == TRUE
Parameters:
s socket
byte Pointer to a byte.
Returns:
TRUE if a byte was read. FALSE if byte was not read.
Examples:
ex_tcp.c, and ex_tcp_echo.c.

WORD TCPGetArray ( TCP_SOCKET  s,
BYTE buffer,
WORD  count 
)

Read the requested number of bytes from the given socket into the given buffer.

Pre-Condition:
TCPInit() is already called AND
TCPIsGetReady(s) == TRUE
Parameters:
s socket
[in] buffer Buffer to hold received data.
count Buffer length
Returns:
Number of bytes loaded into buffer.

SOCKET_INFO* TCPGetSocketInfo ( TCP_SOCKET  s  ) 

Returns a pointer to the SOCKET_INFO structure for the given socket.

Pre-Condition:
TCPInit() is already called.
Parameters:
s socket
Returns:
Returns a pointer to the SOCKET_INFO structure for the given socket.

void TCPInit ( void   ) 

Initialize all socket info. This function is called only one during lifetime of the application.

BOOL TCPIsConnected ( TCP_SOCKET  s  ) 

A socket is said to be connected if it is not in LISTEN and CLOSED mode. Socket may be in SYN_RCVD or FIN_WAIT_1 and may contain socket data.

Pre-Condition:
TCPInit() is already called.
Parameters:
s Socket to be checked for connection.
Returns:
TRUE if given socket is connected
FALSE if given socket is not connected.
Examples:
ex_tcp.c, ex_tcp_client.c, and ex_tcp_echo.c.

BOOL TCPIsGetReady ( TCP_SOCKET  s  ) 

A socket is said to be "Get" ready when it has already received some data. Sometime, a socket may be closed, but it still may contain data. Thus in order to ensure reuse of a socket, caller must make sure that it reads a socket, if it is ready. This function also checks that the given socket is valid, is not equal to INVALID_SOCKET for example

Pre-Condition:
TCPInit() is already called.
Parameters:
s socket to test
Returns:
TRUE if socket 's' contains any data.
FALSE if socket 's' does not contain any data.
Examples:
ex_tcp.c, and ex_tcp_echo.c.

BOOL TCPIsPutReady ( TCP_SOCKET  s  ) 

Each socket maintains only one transmit buffer. Hence until a data packet is acknowledeged by remote node, socket will not be ready for next transmission. All control transmission such as Connect, Disconnect do not consume/reserve any transmit buffer. This function will check:

Pre-Condition:
TCPInit() is already called.
Parameters:
s socket to test
Returns:
TRUE if socket 's' is free to transmit, and it is a valid socket
FALSE if socket 's' is not free to transmit, or an invalid socket was given.
Examples:
ex_tcp_client.c, and ex_tcp_echo.c.

TCP_SOCKET TCPListen ( TCP_PORT  port  ) 

Pre-Condition:
TCPInit() is already called.
Parameters:
port A TCP port to be opened.
Returns:
Given port is opened and returned on success INVALID_SOCKET if no more sockets left.
Examples:
ex_tcp.c, and ex_tcp_echo.c.

BOOL TCPProcess ( NODE_INFO remote,
IP_ADDR localIP,
WORD  len 
)

Performs TCP tasks.

Pre-Condition:
TCPInit() is already called AND
TCP segment is ready in MAC buffer
Parameters:
remote Remote node info
localIP Local IP address
len Total length of TCP semgent.
Returns:
TRUE if this function has completed its task
FALSE otherwise

BOOL TCPPut ( TCP_SOCKET  s,
BYTE  byte 
)

Write the given byte to the given socket's transmit buffer. The data is NOT sent yet, and the TCPFlush() function must be called to send all data contained in the transmit buffer.

Pre-Condition:
TCPIsPutReady() == TRUE
Parameters:
s socket to use
byte a data byte to send
Returns:
TRUE if transmit buffer is still ready to accept more data bytes
FALSE if transmit buffer can no longer accept any more data byte.
If FALSE is returned, then TCPIsPutReady() has to be called again before calling TCPPut() or TCPPutArray() functions!
Examples:
ex_tcp_client.c, and ex_tcp_echo.c.

BOOL TCPPutArray ( TCP_SOCKET  s,
BYTE buffer,
WORD  count 
)

Given number of data bytes from the given array are put into the given socket's transmit buffer. The data is NOT sent yet, and the TCPFlush() function must be called to send all data contained in the transmit buffer.

If there is not enough space in the transmit buffer for all the data, the contents of the transmit buffer will be sent, and this function will return the actual amount of bytes that were sent. In this case, it is VERY IMPORTANT to call the TCPIsPutReady() function again before calling the TCPPut() or TCPPutArray() functions! This will however only happen if the transmit buffer fills up. The transmit buffer for TCP data is = (MAC_TX_BUFFER_SIZE - 54), which is usually 970 bytes. If writing less then this to the transmit buffer before calling TCPFlush(), then this function will always return the requested number of bytes!

Pre-Condition:
TCPIsPutReady() == TRUE
Parameters:
s socket to use
[in] buffer Buffer containing data that has to be sent.
count Number of bytes to send
Returns:
TRUE if transmit buffer is still ready to accept more data bytes
FALSE if transmit buffer can no longer accept any more data byte.
If FALSE is returned, then TCPIsPutReady() has to be called again before calling TCPPut() or TCPPutArray() functions!

void TCPTick ( void   ) 

Each socket FSM is executed for any timeout situation.

Pre-Condition:
TCPInit() is already called.


Variable Documentation

SOCKET_INFO TCB[MAX_SOCKETS]

These are all the sockets supported by this TCP.


Generated on Mon Oct 9 13:22:07 2006 for SBC65EC Web Server by  doxygen 1.4.7