Use total free memory as advertised window. This seems to be sufficient
[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  * Maxmimum advertised TCP window size
215  *
216  * We estimate the TCP window size as the amount of free memory we
217  * have.  This is not strictly accurate (since it ignores any space
218  * already allocated as RX buffers), but it will do for now.
219  *
220  * Since we don't store out-of-order received packets, the
221  * retransmission penalty is that the whole window contents must be
222  * resent.  This suggests keeping the window size small, but bear in
223  * mind that the maximum bandwidth on any link is limited to
224  *
225  *    max_bandwidth = ( tcp_window / round_trip_time )
226  *
227  * With a 48kB window, which probably accurately reflects our amount
228  * of free memory, and a WAN RTT of say 200ms, this gives a maximum
229  * bandwidth of 240kB/s.  This is sufficiently close to realistic that
230  * we will need to be careful that our advertised window doesn't end
231  * up limiting WAN download speeds.
232  *
233  * Finally, since the window goes into a 16-bit field and we cannot
234  * actually use 65536, we use a window size of (65536-4) to ensure
235  * that payloads remain dword-aligned.
236  */
237 #define TCP_MAX_WINDOW_SIZE     ( 65536 - 4 )
238
239 /**
240  * Advertised TCP MSS
241  *
242  * We currently hardcode this to a reasonable value and hope that the
243  * sender uses path MTU discovery.  The alternative is breaking the
244  * abstraction layer so that we can find out the MTU from the IP layer
245  * (which would have to find out from the net device layer).
246  */
247 #define TCP_MSS 1460
248
249 /** TCP maximum segment lifetime
250  *
251  * Currently set to 2 minutes, as per RFC 793.
252  */
253 #define TCP_MSL ( 2 * 60 * TICKS_PER_SEC )
254
255 struct tcp_application;
256
257 /**
258  * TCP operations
259  *
260  */
261 struct tcp_operations {
262         /*
263          * Connection closed
264          *
265          * @v app       TCP application
266          * @v status    Error code, if any
267          *
268          * This is called when the connection is closed for any
269          * reason, including timeouts or aborts.  The status code
270          * contains the negative error number, if the closure is due
271          * to an error.
272          *
273          * When closed() is called, the application no longer has a
274          * valid TCP connection.  Note that connected() may not have
275          * been called before closed(), if the close is due to an
276          * error during connection setup.
277          */
278         void ( * closed ) ( struct tcp_application *app, int status );
279         /**
280          * Connection established
281          *
282          * @v app       TCP application
283          */
284         void ( * connected ) ( struct tcp_application *app );
285         /**
286          * Data acknowledged
287          *
288          * @v app       TCP application
289          * @v len       Length of acknowledged data
290          *
291          * @c len is guaranteed to not exceed the outstanding amount
292          * of unacknowledged data.
293          */
294         void ( * acked ) ( struct tcp_application *app, size_t len );
295         /**
296          * New data received
297          *
298          * @v app       TCP application
299          * @v data      Data
300          * @v len       Length of data
301          */
302         void ( * newdata ) ( struct tcp_application *app,
303                              void *data, size_t len );
304         /**
305          * Transmit data
306          *
307          * @v app       TCP application
308          * @v buf       Temporary data buffer
309          * @v len       Length of temporary data buffer
310          *
311          * The application should transmit whatever it currently wants
312          * to send using tcp_send().  If retransmissions are required,
313          * senddata() will be called again and the application must
314          * regenerate the data.  The easiest way to implement this is
315          * to ensure that senddata() never changes the application's
316          * state.
317          *
318          * The application may use the temporary data buffer to
319          * construct the data to be sent.  Note that merely filling
320          * the buffer will do nothing; the application must call
321          * tcp_send() in order to actually transmit the data.  Use of
322          * the buffer is not compulsory; the application may call
323          * tcp_send() on any block of data.
324          */
325         void ( * senddata ) ( struct tcp_application *app, void *buf,
326                               size_t len );
327 };
328
329 struct tcp_connection;
330
331 /**
332  * A TCP application
333  *
334  * This data structure represents an application with a TCP connection.
335  */
336 struct tcp_application {
337         /** TCP connection data
338          *
339          * This is filled in by TCP calls that initiate a connection,
340          * and reset to NULL when the connection is closed.
341          */
342         struct tcp_connection *conn;
343         /** TCP connection operations table */
344         struct tcp_operations *tcp_op;
345 };
346
347 extern int tcp_connect ( struct tcp_application *app,
348                          struct sockaddr_tcpip *peer,
349                          uint16_t local_port );
350 extern void tcp_close ( struct tcp_application *app );
351 extern int tcp_senddata ( struct tcp_application *app );
352 extern int tcp_send ( struct tcp_application *app, const void *data, 
353                       size_t len );
354
355 extern struct tcpip_protocol tcp_protocol;
356
357 #endif /* _GPXE_TCP_H */