tcp.h
Go to the documentation of this file.
1 /**
2  * @file tcp.h
3  * @brief TCP (Transmission Control Protocol)
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.4.4
29  **/
30 
31 #ifndef _TCP_H
32 #define _TCP_H
33 
34 //Dependencies
35 #include "net_config.h"
36 #include "core/ip.h"
37 
38 //TCP support
39 #ifndef TCP_SUPPORT
40  #define TCP_SUPPORT ENABLED
41 #elif (TCP_SUPPORT != ENABLED && TCP_SUPPORT != DISABLED)
42  #error TCP_SUPPORT parameter is not valid
43 #endif
44 
45 //TCP tick interval
46 #ifndef TCP_TICK_INTERVAL
47  #define TCP_TICK_INTERVAL 100
48 #elif (TCP_TICK_INTERVAL < 10)
49  #error TCP_TICK_INTERVAL parameter is not valid
50 #endif
51 
52 //Maximum segment size
53 #ifndef TCP_MAX_MSS
54  #define TCP_MAX_MSS 1430
55 #elif (TCP_MAX_MSS < 536)
56  #error TCP_MAX_MSS parameter is not valid
57 #endif
58 
59 //Mimimum acceptable segment size
60 #ifndef TCP_MIN_MSS
61  #define TCP_MIN_MSS 64
62 #elif (TCP_MIN_MSS < 1)
63  #error TCP_MIN_MSS parameter is not valid
64 #endif
65 
66 //Default buffer size for transmission
67 #ifndef TCP_DEFAULT_TX_BUFFER_SIZE
68  #define TCP_DEFAULT_TX_BUFFER_SIZE 2860
69 #elif (TCP_DEFAULT_TX_BUFFER_SIZE < 536)
70  #error TCP_DEFAULT_TX_BUFFER_SIZE parameter is not valid
71 #endif
72 
73 //Maximum acceptable size for the send buffer
74 #ifndef TCP_MAX_TX_BUFFER_SIZE
75  #define TCP_MAX_TX_BUFFER_SIZE 22880
76 #elif (TCP_MAX_TX_BUFFER_SIZE < 536)
77  #error TCP_MAX_TX_BUFFER_SIZE parameter is not valid
78 #endif
79 
80 //Default buffer size for reception
81 #ifndef TCP_DEFAULT_RX_BUFFER_SIZE
82  #define TCP_DEFAULT_RX_BUFFER_SIZE 2860
83 #elif (TCP_DEFAULT_RX_BUFFER_SIZE < 536)
84  #error TCP_DEFAULT_RX_BUFFER_SIZE parameter is not valid
85 #endif
86 
87 //Maximum acceptable size for the receive buffer
88 #ifndef TCP_MAX_RX_BUFFER_SIZE
89  #define TCP_MAX_RX_BUFFER_SIZE 22880
90 #elif (TCP_MAX_RX_BUFFER_SIZE < 536)
91  #error TCP_MAX_RX_BUFFER_SIZE parameter is not valid
92 #endif
93 
94 //Default SYN queue size for listening sockets
95 #ifndef TCP_DEFAULT_SYN_QUEUE_SIZE
96  #define TCP_DEFAULT_SYN_QUEUE_SIZE 4
97 #elif (TCP_DEFAULT_SYN_QUEUE_SIZE < 1)
98  #error TCP_DEFAULT_SYN_QUEUE_SIZE parameter is not valid
99 #endif
100 
101 //Maximum SYN queue size for listening sockets
102 #ifndef TCP_MAX_SYN_QUEUE_SIZE
103  #define TCP_MAX_SYN_QUEUE_SIZE 16
104 #elif (TCP_MAX_SYN_QUEUE_SIZE < 1)
105  #error TCP_MAX_SYN_QUEUE_SIZE parameter is not valid
106 #endif
107 
108 //Maximum number of retransmissions
109 #ifndef TCP_MAX_RETRIES
110  #define TCP_MAX_RETRIES 5
111 #elif (TCP_MAX_RETRIES < 1)
112  #error TCP_MAX_RETRIES parameter is not valid
113 #endif
114 
115 //Initial retransmission timeout
116 #ifndef TCP_INITIAL_RTO
117  #define TCP_INITIAL_RTO 1000
118 #elif (TCP_INITIAL_RTO < 100)
119  #error TCP_INITIAL_RTO parameter is not valid
120 #endif
121 
122 //Minimum retransmission timeout
123 #ifndef TCP_MIN_RTO
124  #define TCP_MIN_RTO 1000
125 #elif (TCP_MIN_RTO < 100)
126  #error TCP_MIN_RTO parameter is not valid
127 #endif
128 
129 //Maximum retransmission timeout
130 #ifndef TCP_MAX_RTO
131  #define TCP_MAX_RTO 60000
132 #elif (TCP_MAX_RTO < 1000)
133  #error TCP_MAX_RTO parameter is not valid
134 #endif
135 
136 //Secure initial sequence number generation
137 #ifndef TCP_SECURE_ISN_SUPPORT
138  #define TCP_SECURE_ISN_SUPPORT DISABLED
139 #elif (TCP_SECURE_ISN_SUPPORT != ENABLED && TCP_SECURE_ISN_SUPPORT != DISABLED)
140  #error TCP_SECURE_ISN_SUPPORT parameter is not valid
141 #endif
142 
143 //TCP congestion control
144 #ifndef TCP_CONGEST_CONTROL_SUPPORT
145  #define TCP_CONGEST_CONTROL_SUPPORT ENABLED
146 #elif (TCP_CONGEST_CONTROL_SUPPORT != ENABLED && TCP_CONGEST_CONTROL_SUPPORT != DISABLED)
147  #error TCP_CONGEST_CONTROL_SUPPORT parameter is not valid
148 #endif
149 
150 //Number of duplicate ACKs that triggers fast retransmit algorithm
151 #ifndef TCP_FAST_RETRANSMIT_THRES
152  #define TCP_FAST_RETRANSMIT_THRES 3
153 #elif (TCP_FAST_RETRANSMIT_THRES < 1)
154  #error TCP_FAST_RETRANSMIT_THRES parameter is not valid
155 #endif
156 
157 //Size of the congestion window after the three-way handshake is completed
158 #ifndef TCP_INITIAL_WINDOW
159  #define TCP_INITIAL_WINDOW 3
160 #elif (TCP_INITIAL_WINDOW < 1)
161  #error TCP_INITIAL_WINDOW parameter is not valid
162 #endif
163 
164 //Size of the congestion window after TCP detects loss using its retransmission timer
165 #ifndef TCP_LOSS_WINDOW
166  #define TCP_LOSS_WINDOW 1
167 #elif (TCP_LOSS_WINDOW < 1)
168  #error TCP_LOSS_WINDOW parameter is not valid
169 #endif
170 
171 //Default interval between successive window probes
172 #ifndef TCP_DEFAULT_PROBE_INTERVAL
173  #define TCP_DEFAULT_PROBE_INTERVAL 1000
174 #elif (TCP_DEFAULT_PROBE_INTERVAL < 100)
175  #error TCP_DEFAULT_PROBE_INTERVAL parameter is not valid
176 #endif
177 
178 //Maximum interval between successive window probes
179 #ifndef TCP_MAX_PROBE_INTERVAL
180  #define TCP_MAX_PROBE_INTERVAL 60000
181 #elif (TCP_MAX_PROBE_INTERVAL < 1000)
182  #error TCP_MAX_PROBE_INTERVAL parameter is not valid
183 #endif
184 
185 //Override timeout (should be in the range 0.1 to 1 seconds)
186 #ifndef TCP_OVERRIDE_TIMEOUT
187  #define TCP_OVERRIDE_TIMEOUT 500
188 #elif (TCP_OVERRIDE_TIMEOUT < 100)
189  #error TCP_OVERRIDE_TIMEOUT parameter is not valid
190 #endif
191 
192 //FIN-WAIT-2 timer
193 #ifndef TCP_FIN_WAIT_2_TIMER
194  #define TCP_FIN_WAIT_2_TIMER 4000
195 #elif (TCP_FIN_WAIT_2_TIMER < 1000)
196  #error TCP_FIN_WAIT_2_TIMER parameter is not valid
197 #endif
198 
199 //TIME-WAIT timer
200 #ifndef TCP_2MSL_TIMER
201  #define TCP_2MSL_TIMER 4000
202 #elif (TCP_2MSL_TIMER < 0)
203  #error TCP_2MSL_TIMER parameter is not valid
204 #endif
205 
206 //TCP keep-alive support
207 #ifndef TCP_KEEP_ALIVE_SUPPORT
208  #define TCP_KEEP_ALIVE_SUPPORT DISABLED
209 #elif (TCP_KEEP_ALIVE_SUPPORT != ENABLED && TCP_KEEP_ALIVE_SUPPORT != DISABLED)
210  #error TCP_KEEP_ALIVE_SUPPORT parameter is not valid
211 #endif
212 
213 //Default time interval between last data packet sent and first keep-alive probe
214 #ifndef TCP_DEFAULT_KEEP_ALIVE_IDLE
215  #define TCP_DEFAULT_KEEP_ALIVE_IDLE 60000
216 #elif (TCP_DEFAULT_KEEP_ALIVE_IDLE < 1000)
217  #error TCP_DEFAULT_KEEP_ALIVE_IDLE parameter is not valid
218 #endif
219 
220 //Default time interval between subsequent keep-alive probes
221 #ifndef TCP_DEFAULT_KEEP_ALIVE_INTERVAL
222  #define TCP_DEFAULT_KEEP_ALIVE_INTERVAL 15000
223 #elif (TCP_DEFAULT_KEEP_ALIVE_INTERVAL < 1000)
224  #error TCP_DEFAULT_KEEP_ALIVE_INTERVAL parameter is not valid
225 #endif
226 
227 //Number of keep-alive probes before considering the connection is dead
228 #ifndef TCP_DEFAULT_KEEP_ALIVE_PROBES
229  #define TCP_DEFAULT_KEEP_ALIVE_PROBES 5
230 #elif (TCP_DEFAULT_KEEP_ALIVE_PROBES < 1)
231  #error TCP_DEFAULT_KEEP_ALIVE_PROBES parameter is not valid
232 #endif
233 
234 //Selective acknowledgment support
235 #ifndef TCP_SACK_SUPPORT
236  #define TCP_SACK_SUPPORT DISABLED
237 #elif (TCP_SACK_SUPPORT != ENABLED && TCP_SACK_SUPPORT != DISABLED)
238  #error TCP_SACK_SUPPORT parameter is not valid
239 #endif
240 
241 //Number of SACK blocks
242 #ifndef TCP_MAX_SACK_BLOCKS
243  #define TCP_MAX_SACK_BLOCKS 4
244 #elif (TCP_MAX_SACK_BLOCKS < 1)
245  #error TCP_MAX_SACK_BLOCKS parameter is not valid
246 #endif
247 
248 //Maximum TCP header length
249 #define TCP_MAX_HEADER_LENGTH 60
250 //Default maximum segment size
251 #define TCP_DEFAULT_MSS 536
252 
253 //Sequence number comparison macro
254 #define TCP_CMP_SEQ(a, b) ((int32_t) ((a) - (b)))
255 
256 //C++ guard
257 #ifdef __cplusplus
258 extern "C" {
259 #endif
260 
261 
262 /**
263  * @brief TCP FSM states
264  **/
265 
266 typedef enum
267 {
280 
281 
282 /**
283  * @brief TCP congestion states
284  **/
285 
286 typedef enum
287 {
292 
293 
294 /**
295  * @brief TCP control flags
296  **/
297 
298 typedef enum
299 {
300  TCP_FLAG_FIN = 0x01,
301  TCP_FLAG_SYN = 0x02,
302  TCP_FLAG_RST = 0x04,
303  TCP_FLAG_PSH = 0x08,
304  TCP_FLAG_ACK = 0x10,
305  TCP_FLAG_URG = 0x20
307 
308 
309 /**
310  * @brief TCP option types
311  **/
312 
313 typedef enum
314 {
323 
324 
325 //CC-RX, CodeWarrior or Win32 compiler?
326 #if defined(__CCRX__)
327  #pragma pack
328 #elif defined(__CWCC__) || defined(_WIN32)
329  #pragma pack(push, 1)
330 #endif
331 
332 
333 /**
334  * @brief TCP header
335  **/
336 
338 {
339  uint16_t srcPort; //0-1
340  uint16_t destPort; //2-3
341  uint32_t seqNum; //4-7
342  uint32_t ackNum; //8-11
343 #if defined(_CPU_BIG_ENDIAN) && !defined(__ICCRX__)
344  uint8_t dataOffset : 4; //12
345  uint8_t reserved1 : 4;
346  uint8_t reserved2 : 2; //13
347  uint8_t flags : 6;
348 #else
349  uint8_t reserved1 : 4; //12
350  uint8_t dataOffset : 4;
351  uint8_t flags : 6; //13
352  uint8_t reserved2 : 2;
353 #endif
354  uint16_t window; //14-15
355  uint16_t checksum; //16-17
356  uint16_t urgentPointer; //18-19
357  uint8_t options[]; //20
359 
360 
361 /**
362  * @brief TCP option
363  **/
364 
365 typedef __packed_struct
366 {
367  uint8_t kind;
368  uint8_t length;
369  uint8_t value[];
371 
372 
373 //CC-RX, CodeWarrior or Win32 compiler?
374 #if defined(__CCRX__)
375  #pragma unpack
376 #elif defined(__CWCC__) || defined(_WIN32)
377  #pragma pack(pop)
378 #endif
379 
380 
381 /**
382  * @brief Retransmission queue item
383  **/
384 
385 typedef struct _TcpQueueItem
386 {
393 
394 
395 /**
396  * @brief SYN queue item
397  **/
398 
399 typedef struct _TcpSynQueueItem
400 {
404  uint16_t srcPort;
406  uint32_t isn;
407  uint16_t mss;
408 #if (TCP_SACK_SUPPORT == ENABLED)
410 #endif
412 
413 
414 /**
415  * @brief SACK block
416  **/
417 
418 typedef struct
419 {
420  uint32_t leftEdge;
421  uint32_t rightEdge;
422 } TcpSackBlock;
423 
424 
425 /**
426  * @brief Transmit buffer
427  **/
428 
429 typedef struct
430 {
434 } TcpTxBuffer;
435 
436 
437 /**
438  * @brief Receive buffer
439  **/
440 
441 typedef struct
442 {
446 } TcpRxBuffer;
447 
448 
449 //Tick counter to handle periodic operations
451 
452 //TCP related functions
453 error_t tcpInit(void);
454 
456 
457 uint16_t tcpGetDynamicPort(void);
458 
459 error_t tcpConnect(Socket *socket, const IpAddr *remoteIpAddr,
460  uint16_t remotePort);
461 
463 Socket *tcpAccept(Socket *socket, IpAddr *clientIpAddr, uint16_t *clientPort);
464 
465 error_t tcpSend(Socket *socket, const uint8_t *data, size_t length,
466  size_t *written, uint_t flags);
467 
468 error_t tcpReceive(Socket *socket, uint8_t *data, size_t size,
469  size_t *received, uint_t flags);
470 
473 
475 
477 
478 //C++ guard
479 #ifdef __cplusplus
480 }
481 #endif
482 
483 #endif
@ TCP_CONGEST_STATE_IDLE
Definition: tcp.h:288
Retransmission queue item.
Definition: tcp.h:386
@ TCP_STATE_TIME_WAIT
Definition: tcp.h:278
int bool_t
Definition: compiler_port.h:53
uint_t chunkCount
Definition: tcp.h:431
#define TCP_MAX_HEADER_LENGTH
Definition: tcp.h:249
uint_t sacked
Definition: tcp.h:389
uint8_t header[TCP_MAX_HEADER_LENGTH]
Definition: tcp.h:391
error_t tcpReceive(Socket *socket, uint8_t *data, size_t size, size_t *received, uint_t flags)
Receive data from a connected socket.
Definition: tcp.c:659
@ TCP_OPTION_END
Definition: tcp.h:315
IP network address.
Definition: ip.h:90
TcpCongestState
TCP congestion states.
Definition: tcp.h:287
@ TCP_FLAG_FIN
Definition: tcp.h:300
uint16_t checksum
Definition: tcp.h:355
@ TCP_STATE_FIN_WAIT_1
Definition: tcp.h:275
uint16_t mss
Definition: tcp.h:407
IpAddr srcAddr
Definition: tcp.h:403
uint8_t data[]
Definition: ethernet.h:222
TcpFlags
TCP control flags.
Definition: tcp.h:299
uint32_t rightEdge
Definition: tcp.h:421
@ TCP_STATE_CLOSE_WAIT
Definition: tcp.h:273
IpAddr destAddr
Definition: tcp.h:405
uint16_t destPort
Definition: tcp.h:340
uint16_t srcPort
Definition: tcp.h:404
struct _TcpSynQueueItem * next
Definition: tcp.h:401
@ TCP_FLAG_ACK
Definition: tcp.h:304
uint16_t window
Definition: tcp.h:354
#define N(size)
Definition: net_mem.h:64
uint_t length
Definition: tcp.h:388
@ TCP_OPTION_WINDOW_SCALE_FACTOR
Definition: tcp.h:318
IP pseudo header.
Definition: ip.h:110
TcpOptionKind
TCP option types.
Definition: tcp.h:314
TcpState
TCP FSM states.
Definition: tcp.h:267
uint_t chunkCount
Definition: tcp.h:443
@ TCP_OPTION_SACK_PERMITTED
Definition: tcp.h:319
error_t
Error codes.
Definition: error.h:43
uint32_t seqNum
Definition: tcp.h:341
Structure describing a chunk of data.
Definition: net_mem.h:77
@ TCP_OPTION_TIMESTAMP
Definition: tcp.h:321
error_t tcpListen(Socket *socket, uint_t backlog)
Place a socket in the listening state.
Definition: tcp.c:294
#define TCP_MAX_RX_BUFFER_SIZE
Definition: tcp.h:89
struct _TcpQueueItem * next
Definition: tcp.h:387
TcpState tcpGetState(Socket *socket)
Get the current state of the TCP FSM.
Definition: tcp.c:1021
@ TCP_CONGEST_STATE_LOSS_RECOVERY
Definition: tcp.h:290
int_t socket(int_t family, int_t type, int_t protocol)
Create a socket that is bound to a specific transport service provider.
Definition: bsd_socket.c:65
uint8_t reserved1
Definition: tcp.h:349
#define NetInterface
Definition: net.h:36
NetInterface * interface
Definition: tcp.h:402
systime_t tcpTickCounter
Definition: tcp.c:49
struct _TcpSynQueueItem TcpSynQueueItem
SYN queue item.
error_t tcpAbort(Socket *socket)
Abort an existing TCP connection.
Definition: tcp.c:958
@ TCP_CONGEST_STATE_RECOVERY
Definition: tcp.h:289
TcpOption
Definition: tcp.h:370
uint16_t tcpGetDynamicPort(void)
Get an ephemeral port number.
Definition: tcp.c:106
@ TCP_STATE_SYN_SENT
Definition: tcp.h:270
struct _TcpQueueItem TcpQueueItem
Retransmission queue item.
@ TCP_FLAG_RST
Definition: tcp.h:302
uint_t maxChunkCount
Definition: tcp.h:444
@ TCP_FLAG_SYN
Definition: tcp.h:301
uint32_t isn
Definition: tcp.h:406
uint8_t length
Definition: tcp.h:368
@ TCP_STATE_LAST_ACK
Definition: tcp.h:274
@ TCP_OPTION_NOP
Definition: tcp.h:316
@ TCP_STATE_CLOSING
Definition: tcp.h:277
#define TCP_MAX_TX_BUFFER_SIZE
Definition: tcp.h:75
uint32_t systime_t
System time.
@ TCP_STATE_CLOSED
Definition: tcp.h:268
@ TCP_STATE_LISTEN
Definition: tcp.h:269
uint8_t flags
Definition: tcp.h:351
uint8_t reserved2
Definition: tcp.h:352
IpPseudoHeader pseudoHeader
Definition: tcp.h:390
SACK block.
Definition: tcp.h:419
@ TCP_OPTION_SACK
Definition: tcp.h:320
uint32_t ackNum
Definition: tcp.h:342
IPv4 and IPv6 common routines.
@ TCP_FLAG_URG
Definition: tcp.h:305
typedef __packed_struct
TCP header.
Definition: tcp.h:338
#define Socket
Definition: socket.h:36
@ TCP_STATE_FIN_WAIT_2
Definition: tcp.h:276
uint8_t value[]
Definition: tcp.h:369
uint8_t dataOffset
Definition: tcp.h:350
uint32_t leftEdge
Definition: tcp.h:420
error_t tcpSetInitialRto(NetInterface *interface, systime_t initialRto)
Set TCP initial retransmission timeout.
Definition: tcp.c:77
@ TCP_STATE_SYN_RECEIVED
Definition: tcp.h:271
SYN queue item.
Definition: tcp.h:400
uint8_t options[]
Definition: tcp.h:357
error_t tcpInit(void)
TCP related initialization.
Definition: tcp.c:60
uint_t maxChunkCount
Definition: tcp.h:432
error_t tcpConnect(Socket *socket, const IpAddr *remoteIpAddr, uint16_t remotePort)
Establish a TCP connection.
Definition: tcp.c:146
@ TCP_OPTION_MAX_SEGMENT_SIZE
Definition: tcp.h:317
Receive buffer.
Definition: tcp.h:442
Transmit buffer.
Definition: tcp.h:430
unsigned int uint_t
Definition: compiler_port.h:50
TcpHeader
Definition: tcp.h:358
Socket * tcpAccept(Socket *socket, IpAddr *clientIpAddr, uint16_t *clientPort)
Permit an incoming connection attempt on a TCP socket.
Definition: tcp.c:321
bool_t sackPermitted
Definition: tcp.h:409
@ TCP_STATE_ESTABLISHED
Definition: tcp.h:272
error_t tcpShutdown(Socket *socket, uint_t how)
Shutdown gracefully reception, transmission, or both.
Definition: tcp.c:820
Socket * tcpKillOldestConnection(void)
Kill the oldest socket in the TIME-WAIT state.
Definition: tcp.c:1045
uint16_t urgentPointer
Definition: tcp.h:356
error_t tcpSend(Socket *socket, const uint8_t *data, size_t length, size_t *written, uint_t flags)
Send data to a connected socket.
Definition: tcp.c:532
@ TCP_FLAG_PSH
Definition: tcp.h:303