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 ) & 0xff )
  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) << 16 )
  69 #define TCP_FLAGS_RCVD(state) ( ( (state) >> 16 ) & 0xff )
  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 */