f0ac8ace366e8539703b54d1a20a4b86ba34642e
[gpxe.git] / src / include / gpxe / tcp.h
1 #ifndef _GPXE_TCP_H
2 #define _GPXE_TCP_H
3
4 /** @file
5  *
6  * TCP protocol
7  *
8  * This file defines the gPXE TCP API.
9  *
10  */
11
12 #include "latch.h"
13 #include <gpxe/tcpip.h>
14
15 /**
16  * A TCP header
17  */
18 struct tcp_header {
19         uint16_t src;           /* Source port */
20         uint16_t dest;          /* Destination port */
21         uint32_t seq;           /* Sequence number */
22         uint32_t ack;           /* Acknowledgement number */
23         uint8_t hlen;           /* Header length (4), Reserved (4) */
24         uint8_t flags;          /* Reserved (2), Flags (6) */
25         uint16_t win;           /* Advertised window */
26         uint16_t csum;          /* Checksum */
27         uint16_t urg;           /* Urgent pointer */
28 };
29
30 /*
31  * TCP flags
32  */
33 #define TCP_CWR         0x80
34 #define TCP_ECE         0x40
35 #define TCP_URG         0x20
36 #define TCP_ACK         0x10
37 #define TCP_PSH         0x08
38 #define TCP_RST         0x04
39 #define TCP_SYN         0x02
40 #define TCP_FIN         0x01
41
42 /**
43 * @defgroup tcpstates TCP states
44 *
45 * The TCP state is defined by a combination of the flags that have
46 * been sent to the peer, the flags that have been acknowledged by the
47 * peer, and the flags that have been received from the peer.
48 *
49 * @{
50 */
51
52 /** TCP flags that have been sent in outgoing packets */
53 #define TCP_STATE_SENT(flags) ( (flags) << 0 )
54 #define TCP_FLAGS_SENT(state) ( ( (state) >> 0 ) & 0xff )
55
56 /** TCP flags that have been acknowledged by the peer
57  *
58  * Note that this applies only to SYN and FIN.
59  */
60 #define TCP_STATE_ACKED(flags) ( (flags) << 8 )
61 #define TCP_FLAGS_ACKED(state) ( ( (state) >> 8 ) & 0x03 )
62
63 /** TCP flags that have been received from the peer
64  *
65  * Note that this applies only to SYN and FIN, and that once SYN has
66  * been received, we should always be sending ACK.
67  */
68 #define TCP_STATE_RCVD(flags) ( (flags) << 12 )
69 #define TCP_FLAGS_RCVD(state) ( ( (state) >> 12 ) & 0x03 )
70
71 /** TCP flags that are currently being sent in outgoing packets */
72 #define TCP_FLAGS_SENDING(state) \
73         ( TCP_FLAGS_SENT ( state ) & ~TCP_FLAGS_ACKED ( state ) )
74
75 /** CLOSED
76  *
77  * The connection has not yet been used for anything.
78  */
79 #define TCP_CLOSED TCP_RST
80
81 /** LISTEN
82  *
83  * Not currently used as a state; we have no support for listening
84  * connections.  Given a unique value to avoid compiler warnings.
85  */
86 #define TCP_LISTEN 0
87
88 /** SYN_SENT
89  *
90  * SYN has been sent, nothing has yet been received or acknowledged.
91  */
92 #define TCP_SYN_SENT    ( TCP_STATE_SENT ( TCP_SYN ) )
93
94 /** SYN_RCVD
95  *
96  * SYN has been sent but not acknowledged, SYN has been received.
97  */
98 #define TCP_SYN_RCVD    ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK ) |            \
99                           TCP_STATE_RCVD ( TCP_SYN ) )
100
101 /** ESTABLISHED
102  *
103  * SYN has been sent and acknowledged, SYN has been received.
104  */
105 #define TCP_ESTABLISHED ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK ) |            \
106                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
107                           TCP_STATE_RCVD ( TCP_SYN ) )
108
109 /** FIN_WAIT_1
110  *
111  * SYN has been sent and acknowledged, SYN has been received, FIN has
112  * been sent but not acknowledged, FIN has not been received.
113  *
114  * RFC 793 shows that we can enter FIN_WAIT_1 without have had SYN
115  * acknowledged, i.e. if the application closes the connection after
116  * sending and receiving SYN, but before having had SYN acknowledged.
117  * However, we have to *pretend* that SYN has been acknowledged
118  * anyway, otherwise we end up sending SYN and FIN in the same
119  * sequence number slot.  Therefore, when we transition from SYN_RCVD
120  * to FIN_WAIT_1, we have to remember to set TCP_STATE_ACKED(TCP_SYN)
121  * and increment our sequence number.
122  */
123 #define TCP_FIN_WAIT_1  ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
124                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
125                           TCP_STATE_RCVD ( TCP_SYN ) )
126
127 /** FIN_WAIT_2
128  *
129  * SYN has been sent and acknowledged, SYN has been received, FIN has
130  * been sent and acknowledged, FIN ha not been received.
131  */
132 #define TCP_FIN_WAIT_2  ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
133                           TCP_STATE_ACKED ( TCP_SYN | TCP_FIN ) |           \
134                           TCP_STATE_RCVD ( TCP_SYN ) )
135
136 /** CLOSING / LAST_ACK
137  *
138  * SYN has been sent and acknowledged, SYN has been received, FIN has
139  * been sent but not acknowledged, FIN has been received.
140  *
141  * This state actually encompasses both CLOSING and LAST_ACK; they are
142  * identical with the definition of state that we use.  I don't
143  * *believe* that they need to be distinguished.
144  */
145 #define TCP_CLOSING_OR_LAST_ACK                                             \
146                         ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
147                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
148                           TCP_STATE_RCVD ( TCP_SYN | TCP_FIN ) )
149
150 /** TIME_WAIT
151  *
152  * SYN has been sent and acknowledged, SYN has been received, FIN has
153  * been sent and acknowledged, FIN has been received.
154  */
155 #define TCP_TIME_WAIT   ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
156                           TCP_STATE_ACKED ( TCP_SYN | TCP_FIN ) |           \
157                           TCP_STATE_RCVD ( TCP_SYN | TCP_FIN ) )
158
159 /** CLOSE_WAIT
160  *
161  * SYN has been sent and acknowledged, SYN has been received, FIN has
162  * been received.
163  */
164 #define TCP_CLOSE_WAIT  ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK ) |            \
165                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
166                           TCP_STATE_RCVD ( TCP_SYN | TCP_FIN ) )
167
168 /** Can send data in current state
169  *
170  * We can send data if and only if we have had our SYN acked and we
171  * have not yet sent our FIN.
172  */
173 #define TCP_CAN_SEND_DATA(state)                                            \
174         ( ( (state) & ( TCP_STATE_ACKED ( TCP_SYN ) |                       \
175                         TCP_STATE_SENT ( TCP_FIN ) ) )                      \
176           == TCP_STATE_ACKED ( TCP_SYN ) )
177
178 /** Have closed gracefully
179  *
180  * We have closed gracefully if we have both received a FIN and had
181  * our own FIN acked.
182  */
183 #define TCP_CLOSED_GRACEFULLY(state)                                        \
184         ( ( (state) & ( TCP_STATE_ACKED ( TCP_FIN ) |                       \
185                         TCP_STATE_RCVD ( TCP_FIN ) ) )                      \
186           == ( TCP_STATE_ACKED ( TCP_FIN ) | TCP_STATE_RCVD ( TCP_FIN ) ) )
187
188 /** @} */
189
190 /** Mask for TCP header length field */
191 #define TCP_MASK_HLEN   0xf0
192
193 /** Smallest port number on which a TCP connection can listen */
194 #define TCP_MIN_PORT 1
195
196 /* Some PKB constants */
197 #define MAX_HDR_LEN     100
198 #define MAX_PKB_LEN     1500
199 #define MIN_PKB_LEN     MAX_HDR_LEN + 100 /* To account for padding by LL */
200
201 /**
202  * Advertised TCP window size
203  *
204  * Our TCP window is actually limited by the amount of space available
205  * for RX packets in the NIC's RX ring; we tend to populate the rings
206  * with far fewer descriptors than a typical driver.  Since we have no
207  * way of knowing how much of this RX ring space will be available for
208  * received TCP packets (consider, for example, that they may all be
209  * consumed by a series of unrelated ARP requests between other
210  * machines on the network), it is actually not even theoretically
211  * possible for us to specify an accurate window size.  We therefore
212  * guess an arbitrary number that is empirically as large as possible
213  * while avoiding retransmissions due to dropped packets.
214  */
215 #define TCP_WINDOW_SIZE 2048
216
217 /** TCP maximum segment lifetime
218  *
219  * Currently set to 2 minutes, as per RFC 793.
220  */
221 #define TCP_MSL ( 2 * 60 * TICKS_PER_SEC )
222
223 struct tcp_application;
224
225 /**
226  * TCP operations
227  *
228  */
229 struct tcp_operations {
230         /*
231          * Connection closed
232          *
233          * @v app       TCP application
234          * @v status    Error code, if any
235          *
236          * This is called when the connection is closed for any
237          * reason, including timeouts or aborts.  The status code
238          * contains the negative error number, if the closure is due
239          * to an error.
240          *
241          * When closed() is called, the application no longer has a
242          * valid TCP connection.  Note that connected() may not have
243          * been called before closed(), if the close is due to an
244          * error during connection setup.
245          */
246         void ( * closed ) ( struct tcp_application *app, int status );
247         /**
248          * Connection established
249          *
250          * @v app       TCP application
251          */
252         void ( * connected ) ( struct tcp_application *app );
253         /**
254          * Data acknowledged
255          *
256          * @v app       TCP application
257          * @v len       Length of acknowledged data
258          *
259          * @c len is guaranteed to not exceed the outstanding amount
260          * of unacknowledged data.
261          */
262         void ( * acked ) ( struct tcp_application *app, size_t len );
263         /**
264          * New data received
265          *
266          * @v app       TCP application
267          * @v data      Data
268          * @v len       Length of data
269          */
270         void ( * newdata ) ( struct tcp_application *app,
271                              void *data, size_t len );
272         /**
273          * Transmit data
274          *
275          * @v app       TCP application
276          * @v buf       Temporary data buffer
277          * @v len       Length of temporary data buffer
278          *
279          * The application should transmit whatever it currently wants
280          * to send using tcp_send().  If retransmissions are required,
281          * senddata() will be called again and the application must
282          * regenerate the data.  The easiest way to implement this is
283          * to ensure that senddata() never changes the application's
284          * state.
285          *
286          * The application may use the temporary data buffer to
287          * construct the data to be sent.  Note that merely filling
288          * the buffer will do nothing; the application must call
289          * tcp_send() in order to actually transmit the data.  Use of
290          * the buffer is not compulsory; the application may call
291          * tcp_send() on any block of data.
292          */
293         void ( * senddata ) ( struct tcp_application *app, void *buf,
294                               size_t len );
295 };
296
297 struct tcp_connection;
298
299 /**
300  * A TCP application
301  *
302  * This data structure represents an application with a TCP connection.
303  */
304 struct tcp_application {
305         /** TCP connection data
306          *
307          * This is filled in by TCP calls that initiate a connection,
308          * and reset to NULL when the connection is closed.
309          */
310         struct tcp_connection *conn;
311         /** TCP connection operations table */
312         struct tcp_operations *tcp_op;
313 };
314
315 extern int tcp_connect ( struct tcp_application *app,
316                          struct sockaddr_tcpip *peer,
317                          uint16_t local_port );
318 extern void tcp_close ( struct tcp_application *app );
319 extern int tcp_senddata ( struct tcp_application *app );
320 extern int tcp_send ( struct tcp_application *app, const void *data, 
321                       size_t len );
322
323 extern struct tcpip_protocol tcp_protocol;
324
325 #endif /* _GPXE_TCP_H */