xref: /FreeRTOS-Plus-TCP-v4.0.0/source/include/FreeRTOS_TCP_IP.h (revision 2d3f4daa567ffe71aeda2e0f6d0bc02850db0627) 
1 /*
2  * FreeRTOS+TCP <DEVELOPMENT BRANCH>
3  * Copyright (C) 2022 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
4  *
5  * SPDX-License-Identifier: MIT
6  *
7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
8  * this software and associated documentation files (the "Software"), to deal in
9  * the Software without restriction, including without limitation the rights to
10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11  * the Software, and to permit persons to whom the Software is furnished to do so,
12  * subject to the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be included in all
15  * copies or substantial portions of the Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23  *
24  * http://aws.amazon.com/freertos
25  * http://www.FreeRTOS.org
26  */
27 
28 #ifndef FREERTOS_TCP_IP_H
29 #define FREERTOS_TCP_IP_H
30 
31 /* *INDENT-OFF* */
32 #ifdef __cplusplus
33     extern "C" {
34 #endif
35 /* *INDENT-ON* */
36 
37 /**
38  * @brief Process the received TCP packet.
39  *
40  */
41 BaseType_t xProcessReceivedTCPPacket( NetworkBufferDescriptor_t * pxDescriptor );
42 
43 /**
44  * @brief Process the received TCP packet.
45  */
46 BaseType_t xProcessReceivedTCPPacket_IPV4( NetworkBufferDescriptor_t * pxDescriptor );
47 
48 /**
49  * @brief Process the received TCP packet.
50  */
51 BaseType_t xProcessReceivedTCPPacket_IPV6( NetworkBufferDescriptor_t * pxDescriptor );
52 
53 typedef enum eTCP_STATE
54 {
55     /* Comments about the TCP states are borrowed from the very useful
56      * Wiki page:
57      * http://en.wikipedia.org/wiki/Transmission_Control_Protocol */
58     eCLOSED = 0U,  /* 0 (server + client) no connection state at all. */
59     eTCP_LISTEN,   /* 1 (server) waiting for a connection request
60                     * from any remote TCP and port. */
61     eCONNECT_SYN,  /* 2 (client) internal state: socket wants to send
62                     * a connect */
63     eSYN_FIRST,    /* 3 (server) Just created, must ACK the SYN request. */
64     eSYN_RECEIVED, /* 4 (server) waiting for a confirming connection request
65                     * acknowledgement after having both received and sent a connection request. */
66     eESTABLISHED,  /* 5 (server + client) an open connection, data received can be
67                     * delivered to the user. The normal state for the data transfer phase of the connection. */
68     eFIN_WAIT_1,   /* 6 (server + client) waiting for a connection termination request from the remote TCP,
69                     * or an acknowledgement of the connection termination request previously sent. */
70     eFIN_WAIT_2,   /* 7 (server + client) waiting for a connection termination request from the remote TCP. */
71     eCLOSE_WAIT,   /* 8 (server + client) waiting for a connection termination request from the local user. */
72     eCLOSING,      /* 9 (server + client) waiting for a connection termination request acknowledgement from the remote TCP. */
73     eLAST_ACK,     /*10 (server + client) waiting for an acknowledgement of the connection termination request
74                     * previously sent to the remote TCP
75                     * (which includes an acknowledgement of its connection termination request). */
76     eTIME_WAIT,    /*11 (either server or client) waiting for enough time to pass to be sure the remote TCP received the
77                     * acknowledgement of its connection termination request. [According to RFC 793 a connection can
78                     * stay in TIME-WAIT for a maximum of four minutes known as a MSL (maximum segment lifetime).] */
79 } eIPTCPState_t;
80 
81 /*
82  * The meaning of the TCP flags:
83  */
84 #define tcpTCP_FLAG_FIN     ( ( uint8_t ) 0x01U )                           /**< No more data from sender. */
85 #define tcpTCP_FLAG_SYN     ( ( uint8_t ) 0x02U )                           /**< Synchronize sequence numbers. */
86 #define tcpTCP_FLAG_RST     ( ( uint8_t ) 0x04U )                           /**< Reset the connection. */
87 #define tcpTCP_FLAG_PSH     ( ( uint8_t ) 0x08U )                           /**< Push function: please push buffered data to the recv application. */
88 #define tcpTCP_FLAG_ACK     ( ( uint8_t ) 0x10U )                           /**< Acknowledgment field is significant. */
89 #define tcpTCP_FLAG_URG     ( ( uint8_t ) 0x20U )                           /**< Urgent pointer field is significant. */
90 #define tcpTCP_FLAG_ECN     ( ( uint8_t ) 0x40U )                           /**< ECN-Echo. */
91 #define tcpTCP_FLAG_CWR     ( ( uint8_t ) 0x80U )                           /**< Congestion Window Reduced. */
92 
93 #define tcpTCP_FLAG_CTRL    ( ( uint8_t ) 0x1FU )                           /**< A mask to filter all protocol flags. */
94 
95 
96 /*
97  * A few values of the TCP options:
98  */
99 #define tcpTCP_OPT_END               0U                  /**< End of TCP options list. */
100 #define tcpTCP_OPT_NOOP              1U                  /**< "No-operation" TCP option. */
101 #define tcpTCP_OPT_MSS               2U                  /**< Maximum segment size TCP option. */
102 #define tcpTCP_OPT_WSOPT             3U                  /**< TCP Window Scale Option (3-byte long). */
103 #define tcpTCP_OPT_SACK_P            4U                  /**< Advertise that SACK is permitted. */
104 #define tcpTCP_OPT_SACK_A            5U                  /**< SACK option with first/last. */
105 #define tcpTCP_OPT_TIMESTAMP         8U                  /**< Time-stamp option. */
106 
107 
108 #define tcpTCP_OPT_MSS_LEN           4U                  /**< Length of TCP MSS option. */
109 #define tcpTCP_OPT_WSOPT_LEN         3U                  /**< Length of TCP WSOPT option. */
110 
111 #define tcpTCP_OPT_TIMESTAMP_LEN     10                  /**< fixed length of the time-stamp option. */
112 
113 /** @brief
114  * Minimum segment length as outlined by RFC 791 section 3.1.
115  * Minimum segment length ( 536 ) = Minimum MTU ( 576 ) - IP Header ( 20 ) - TCP Header ( 20 ).
116  */
117 #define tcpMINIMUM_SEGMENT_LENGTH    536U
118 
119 /** @brief
120  * The macro tcpNOW_CONNECTED() is use to determine if the connection makes a
121  * transition from connected to non-connected and vice versa.
122  * tcpNOW_CONNECTED() returns true when the status has one of these values:
123  * eESTABLISHED, eFIN_WAIT_1, eFIN_WAIT_2, eCLOSING, eLAST_ACK, eTIME_WAIT
124  * Technically the connection status is closed earlier, but the library wants
125  * to prevent that the socket will be deleted before the last ACK has been
126  * and thus causing a 'RST' packet on either side.
127  */
128 #define tcpNOW_CONNECTED( status ) \
129     ( ( ( ( status ) >= ( BaseType_t ) eESTABLISHED ) && ( ( status ) != ( BaseType_t ) eCLOSE_WAIT ) ) ? 1 : 0 )
130 
131 /** @brief
132  * The highest 4 bits in the TCP offset byte indicate the total length of the
133  * TCP header, divided by 4.
134  */
135 #define tcpVALID_BITS_IN_TCP_OFFSET_BYTE    ( 0xF0U )
136 
137 /*
138  * Acknowledgements to TCP data packets may be delayed as long as more is being expected.
139  * A normal delay would be 200ms. Here a much shorter delay of 20 ms is being used to
140  * gain performance.
141  */
142 #define tcpDELAYED_ACK_SHORT_DELAY_MS       ( 2 )           /**< Should not become smaller than 1. */
143 #define tcpDELAYED_ACK_LONGER_DELAY_MS      ( 20 )          /**< Longer delay for ACK. */
144 
145 
146 /** @brief
147  * The MSS (Maximum Segment Size) will be taken as large as possible. However, packets with
148  * an MSS of 1460 bytes won't be transported through the internet.  The MSS will be reduced
149  * to 1400 bytes.
150  */
151 #define tcpREDUCED_MSS_THROUGH_INTERNET    ( 1400 )
152 
153 /** @brief
154  * When there are no TCP options, the TCP offset equals 20 bytes, which is stored as
155  * the number 5 (words) in the higher nibble of the TCP-offset byte.
156  */
157 #define tcpTCP_OFFSET_LENGTH_BITS          ( 0xf0U )
158 #define tcpTCP_OFFSET_STANDARD_LENGTH      ( 0x50U )          /**< Standard TCP packet offset. */
159 
160 
161 /** @brief
162  * Each TCP socket is checked regularly to see if it can send data packets.
163  * By default, the maximum number of packets sent during one check is limited to 8.
164  * This amount may be further limited by setting the socket's TX window size.
165  */
166 #if ( !defined( SEND_REPEATED_COUNT ) )
167     #define SEND_REPEATED_COUNT    ( 8 )
168 #endif /* !defined( SEND_REPEATED_COUNT ) */
169 
170 /** @brief
171  * Define a maximum period of time (ms) to leave a TCP-socket unattended.
172  * When a TCP timer expires, retries and keep-alive messages will be checked.
173  */
174 #ifndef tcpMAXIMUM_TCP_WAKEUP_TIME_MS
175     #define tcpMAXIMUM_TCP_WAKEUP_TIME_MS    20000U
176 #endif
177 
178 struct xSOCKET;
179 
180 /*
181  * For anti-hang protection and TCP keep-alive messages.  Called in two places:
182  * after receiving a packet and after a state change.  The socket's alive timer
183  * may be reset.
184  */
185 void prvTCPTouchSocket( struct xSOCKET * pxSocket );
186 
187 /*
188  * Calculate when this socket needs to be checked to do (re-)transmissions.
189  */
190 TickType_t prvTCPNextTimeout( struct xSOCKET * pxSocket );
191 
192 
193 /* *INDENT-OFF* */
194 #ifdef __cplusplus
195     } /* extern "C" */
196 #endif
197 /* *INDENT-ON* */
198 
199 #endif /* FREERTOS_TCP_IP_H */
200