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.
 #define TCP_START_TIMEOUT_VAL   ((TICK)TICK_SECOND * (TICK)60)

 //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

#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   ((TICK16) ((TICK16)TICKS_PER_SECOND * (TICK16)60) )
#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 BYTE	TCP_SOCKET
typedef enum _TCP_STATE	TCP_STATE
Enumerations
enum	_TCP_STATE {   TCP_CLOSED, TCP_LISTEN, TCP_SYN_RCVD, TCP_SYN_SENT,   TCP_EST, TCP_FIN_WAIT_1, TCP_CLOSING, TCP_TIMED_WAIT,   TCP_SEND_RST, TCP_DATA_READY, TCP_LAST_ACK, TCP_CLOSE,   TCP_INVALID }
Functions
TCP_SOCKET	TCPConnect (NODE_INFO *remote, WORD port)
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_INFO *	TCPGetSocketInfo (TCP_SOCKET s)
void	TCPInit (void)
BOOL	TCPIsConnected (TCP_SOCKET s)
BOOL	TCPIsGetReady (TCP_SOCKET s)
BOOL	TCPIsPutReady (TCP_SOCKET s)
TCP_SOCKET	TCPListen (WORD 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 (  s   )     (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   ((TICK16) ((TICK16)TICKS_PER_SECOND * (TICK16)60) )

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 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_CLOSED  RFC793 CLOSED. TCP_LISTEN  RFC793 LISTEN. TCP_SYN_RCVD  RFC793 SYN-RECEIVED. TCP_SYN_SENT  RFC793 SYN-SENT. TCP_EST  RFC793 ESTABLISHED. TCP_FIN_WAIT_1  RFC793 FIN-WAIT-1. TCP_CLOSING  RFC793 CLOSING. TCP_TIMED_WAIT  RFC793 TIME-WAIT. TCP_SEND_RST  TCP_DATA_READY  TCP_LAST_ACK  RFC793 LAST-ACK. TCP_CLOSE  TCP_INVALID

---

Function Documentation

TCP_SOCKET TCPConnect (  NODE_INFO *  remote, WORD  port )

By default this function is not included in source. You must define STACK_CLIENT_MODE to be able to use this function. Pre-Condition: TCPInit() is already called. Parameters: remote  Remote node address info port  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.

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, 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: If the given socket is valid, is not equal to INVALID_SOCKET for example If there is an available TX Buffer for writing data to via TCPPut() and TCPPutArray() functions. If the given socket is ready for transmission 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 (  WORD  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.

---