Increase window size to 64kB. Line rate downloads on a 100Mbps link,
[people/xl0/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 MSS option
32  */
33 struct tcp_mss_option {
34         uint8_t kind;
35         uint8_t length;
36         uint16_t mss;
37 };
38
39 /** Code for the TCP MSS option */
40 #define TCP_OPTION_MSS 2
41
42 /*
43  * TCP flags
44  */
45 #define TCP_CWR         0x80
46 #define TCP_ECE         0x40
47 #define TCP_URG         0x20
48 #define TCP_ACK         0x10
49 #define TCP_PSH         0x08
50 #define TCP_RST         0x04
51 #define TCP_SYN         0x02
52 #define TCP_FIN         0x01
53
54 /**
55 * @defgroup tcpstates TCP states
56 *
57 * The TCP state is defined by a combination of the flags that have
58 * been sent to the peer, the flags that have been acknowledged by the
59 * peer, and the flags that have been received from the peer.
60 *
61 * @{
62 */
63
64 /** TCP flags that have been sent in outgoing packets */
65 #define TCP_STATE_SENT(flags) ( (flags) << 0 )
66 #define TCP_FLAGS_SENT(state) ( ( (state) >> 0 ) & 0xff )
67
68 /** TCP flags that have been acknowledged by the peer
69  *
70  * Note that this applies only to SYN and FIN.
71  */
72 #define TCP_STATE_ACKED(flags) ( (flags) << 8 )
73 #define TCP_FLAGS_ACKED(state) ( ( (state) >> 8 ) & 0xff )
74
75 /** TCP flags that have been received from the peer
76  *
77  * Note that this applies only to SYN and FIN, and that once SYN has
78  * been received, we should always be sending ACK.
79  */
80 #define TCP_STATE_RCVD(flags) ( (flags) << 16 )
81 #define TCP_FLAGS_RCVD(state) ( ( (state) >> 16 ) & 0xff )
82
83 /** TCP flags that are currently being sent in outgoing packets */
84 #define TCP_FLAGS_SENDING(state) \
85         ( TCP_FLAGS_SENT ( state ) & ~TCP_FLAGS_ACKED ( state ) )
86
87 /** CLOSED
88  *
89  * The connection has not yet been used for anything.
90  */
91 #define TCP_CLOSED TCP_RST
92
93 /** LISTEN
94  *
95  * Not currently used as a state; we have no support for listening
96  * connections.  Given a unique value to avoid compiler warnings.
97  */
98 #define TCP_LISTEN 0
99
100 /** SYN_SENT
101  *
102  * SYN has been sent, nothing has yet been received or acknowledged.
103  */
104 #define TCP_SYN_SENT    ( TCP_STATE_SENT ( TCP_SYN ) )
105
106 /** SYN_RCVD
107  *
108  * SYN has been sent but not acknowledged, SYN has been received.
109  */
110 #define TCP_SYN_RCVD    ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK ) |            \
111                           TCP_STATE_RCVD ( TCP_SYN ) )
112
113 /** ESTABLISHED
114  *
115  * SYN has been sent and acknowledged, SYN has been received.
116  */
117 #define TCP_ESTABLISHED ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK ) |            \
118                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
119                           TCP_STATE_RCVD ( TCP_SYN ) )
120
121 /** FIN_WAIT_1
122  *
123  * SYN has been sent and acknowledged, SYN has been received, FIN has
124  * been sent but not acknowledged, FIN has not been received.
125  *
126  * RFC 793 shows that we can enter FIN_WAIT_1 without have had SYN
127  * acknowledged, i.e. if the application closes the connection after
128  * sending and receiving SYN, but before having had SYN acknowledged.
129  * However, we have to *pretend* that SYN has been acknowledged
130  * anyway, otherwise we end up sending SYN and FIN in the same
131  * sequence number slot.  Therefore, when we transition from SYN_RCVD
132  * to FIN_WAIT_1, we have to remember to set TCP_STATE_ACKED(TCP_SYN)
133  * and increment our sequence number.
134  */
135 #define TCP_FIN_WAIT_1  ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
136                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
137                           TCP_STATE_RCVD ( TCP_SYN ) )
138
139 /** FIN_WAIT_2
140  *
141  * SYN has been sent and acknowledged, SYN has been received, FIN has
142  * been sent and acknowledged, FIN ha not been received.
143  */
144 #define TCP_FIN_WAIT_2  ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
145                           TCP_STATE_ACKED ( TCP_SYN | TCP_FIN ) |           \
146                           TCP_STATE_RCVD ( TCP_SYN ) )
147
148 /** CLOSING / LAST_ACK
149  *
150  * SYN has been sent and acknowledged, SYN has been received, FIN has
151  * been sent but not acknowledged, FIN has been received.
152  *
153  * This state actually encompasses both CLOSING and LAST_ACK; they are
154  * identical with the definition of state that we use.  I don't
155  * *believe* that they need to be distinguished.
156  */
157 #define TCP_CLOSING_OR_LAST_ACK                                             \
158                         ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
159                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
160                           TCP_STATE_RCVD ( TCP_SYN | TCP_FIN ) )
161
162 /** TIME_WAIT
163  *
164  * SYN has been sent and acknowledged, SYN has been received, FIN has
165  * been sent and acknowledged, FIN has been received.
166  */
167 #define TCP_TIME_WAIT   ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK | TCP_FIN ) |  \
168                           TCP_STATE_ACKED ( TCP_SYN | TCP_FIN ) |           \
169                           TCP_STATE_RCVD ( TCP_SYN | TCP_FIN ) )
170
171 /** CLOSE_WAIT
172  *
173  * SYN has been sent and acknowledged, SYN has been received, FIN has
174  * been received.
175  */
176 #define TCP_CLOSE_WAIT  ( TCP_STATE_SENT ( TCP_SYN | TCP_ACK ) |            \
177                           TCP_STATE_ACKED ( TCP_SYN ) |                     \
178                           TCP_STATE_RCVD ( TCP_SYN | TCP_FIN ) )
179
180 /** Can send data in current state
181  *
182  * We can send data if and only if we have had our SYN acked and we
183  * have not yet sent our FIN.
184  */
185 #define TCP_CAN_SEND_DATA(state)                                            \
186         ( ( (state) & ( TCP_STATE_ACKED ( TCP_SYN ) |                       \
187                         TCP_STATE_SENT ( TCP_FIN ) ) )                      \
188           == TCP_STATE_ACKED ( TCP_SYN ) )
189
190 /** Have closed gracefully
191  *
192  * We have closed gracefully if we have both received a FIN and had
193  * our own FIN acked.
194  */
195 #define TCP_CLOSED_GRACEFULLY(state)                                        \
196         ( ( (state) & ( TCP_STATE_ACKED ( TCP_FIN ) |                       \
197                         TCP_STATE_RCVD ( TCP_FIN ) ) )                      \
198           == ( TCP_STATE_ACKED ( TCP_FIN ) | TCP_STATE_RCVD ( TCP_FIN ) ) )
199
200 /** @} */
201
202 /** Mask for TCP header length field */
203 #define TCP_MASK_HLEN   0xf0
204
205 /** Smallest port number on which a TCP connection can listen */
206 #define TCP_MIN_PORT 1
207
208 /* Some PKB constants */
209 #define MAX_HDR_LEN     100
210 #define MAX_PKB_LEN     1500
211 #define MIN_PKB_LEN     MAX_HDR_LEN + 100 /* To account for padding by LL */
212
213 /**
214  * Advertised TCP window size
215  *
216  * 
217  * Our TCP window is actually limited by the amount of space available
218  * for RX packets in the NIC's RX ring; we tend to populate the rings
219  * with far fewer descriptors than a typical driver.  This would
220  * result in a desperately small window size, which kills WAN download
221  * performance; the maximum bandwidth on any link is limited to
222  *
223  *    max_bandwidth = ( tcp_window / round_trip_time )
224  *
225  * With a 4kB window, which probably accurately reflects our amount of
226  * buffer space, and a WAN RTT of say 200ms, this gives a maximum
227  * achievable bandwidth of 20kB/s, which is not acceptable.
228  *
229  * We therefore aim to process packets as fast as they arrive, and
230  * advertise an "infinite" window.  If we don't process packets as
231  * fast as they arrive, then we will drop packets and have to incur
232  * the retransmission penalty.
233  *
234  * Since we don't store out-of-order received packets, the
235  * retransmission penalty is that the whole window contents must be
236  * resent.
237  *
238  * We choose to compromise on a window size of 64kB (which is the
239  * maximum that can be represented without using TCP options).  This
240  * gives a maximum bandwidth of 320kB/s at 200ms RTT, which is
241  * probably faster than the actual link bandwidth.  It also limits
242  * retransmissions to 64kB, which is reasonable.
243  *
244  * Finally, since the window goes into a 16-bit field and we cannot
245  * actually use 65536, we use a window size of (65536-4) to ensure
246  * that payloads remain dword-aligned.
247  */
248 #define TCP_WINDOW_SIZE ( 65536 - 4 )
249
250 /**
251  * Advertised TCP MSS
252  *
253  * We currently hardcode this to a reasonable value and hope that the
254  * sender uses path MTU discovery.  The alternative is breaking the
255  * abstraction layer so that we can find out the MTU from the IP layer
256  * (which would have to find out from the net device layer).
257  */
258 #define TCP_MSS 1460
259
260 /** TCP maximum segment lifetime
261  *
262  * Currently set to 2 minutes, as per RFC 793.
263  */
264 #define TCP_MSL ( 2 * 60 * TICKS_PER_SEC )
265
266 struct tcp_application;
267
268 /**
269  * TCP operations
270  *
271  */
272 struct tcp_operations {
273         /*
274          * Connection closed
275          *
276          * @v app       TCP application
277          * @v status    Error code, if any
278          *
279          * This is called when the connection is closed for any
280          * reason, including timeouts or aborts.  The status code
281          * contains the negative error number, if the closure is due
282          * to an error.
283          *
284          * When closed() is called, the application no longer has a
285          * valid TCP connection.  Note that connected() may not have
286          * been called before closed(), if the close is due to an
287          * error during connection setup.
288          */
289         void ( * closed ) ( struct tcp_application *app, int status );
290         /**
291          * Connection established
292          *
293          * @v app       TCP application
294          */
295         void ( * connected ) ( struct tcp_application *app );
296         /**
297          * Data acknowledged
298          *
299          * @v app       TCP application
300          * @v len       Length of acknowledged data
301          *
302          * @c len is guaranteed to not exceed the outstanding amount
303          * of unacknowledged data.
304          */
305         void ( * acked ) ( struct tcp_application *app, size_t len );
306         /**
307          * New data received
308          *
309          * @v app       TCP application
310          * @v data      Data
311          * @v len       Length of data
312          */
313         void ( * newdata ) ( struct tcp_application *app,
314                              void *data, size_t len );
315         /**
316          * Transmit data
317          *
318          * @v app       TCP application
319          * @v buf       Temporary data buffer
320          * @v len       Length of temporary data buffer
321          *
322          * The application should transmit whatever it currently wants
323          * to send using tcp_send().  If retransmissions are required,
324          * senddata() will be called again and the application must
325          * regenerate the data.  The easiest way to implement this is
326          * to ensure that senddata() never changes the application's
327          * state.
328          *
329          * The application may use the temporary data buffer to
330          * construct the data to be sent.  Note that merely filling
331          * the buffer will do nothing; the application must call
332          * tcp_send() in order to actually transmit the data.  Use of
333          * the buffer is not compulsory; the application may call
334          * tcp_send() on any block of data.
335          */
336         void ( * senddata ) ( struct tcp_application *app, void *buf,
337                               size_t len );
338 };
339
340 struct tcp_connection;
341
342 /**
343  * A TCP application
344  *
345  * This data structure represents an application with a TCP connection.
346  */
347 struct tcp_application {
348         /** TCP connection data
349          *
350          * This is filled in by TCP calls that initiate a connection,
351          * and reset to NULL when the connection is closed.
352          */
353         struct tcp_connection *conn;
354         /** TCP connection operations table */
355         struct tcp_operations *tcp_op;
356 };
357
358 extern int tcp_connect ( struct tcp_application *app,
359                          struct sockaddr_tcpip *peer,
360                          uint16_t local_port );
361 extern void tcp_close ( struct tcp_application *app );
362 extern int tcp_senddata ( struct tcp_application *app );
363 extern int tcp_send ( struct tcp_application *app, const void *data, 
364                       size_t len );
365
366 extern struct tcpip_protocol tcp_protocol;
367
368 #endif /* _GPXE_TCP_H */