MdePkg/Include/Protocol/Tcp4.h

   1 /** @file
   2   EFI TCPv4(Transmission Control Protocol version 4) Protocol Definition
   3   The EFI TCPv4 Service Binding Protocol is used to locate EFI TCPv4 Protocol drivers to create
   4   and destroy child of the driver to communicate with other host using TCP protocol.
   5   The EFI TCPv4 Protocol provides services to send and receive data stream.
   6
   7   Copyright (c) 2006 - 2009, Intel Corporation
   8   All rights reserved. This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16   @par Revision Reference:
  17   This Protocol is introduced in UEFI Specification 2.0
  18
  19 **/
  20
  21 #ifndef __EFI_TCP4_PROTOCOL_H__
  22 #define __EFI_TCP4_PROTOCOL_H__
  23
  24 #include <Protocol/Ip4.h>
  25
  26 #define EFI_TCP4_SERVICE_BINDING_PROTOCOL_GUID \
  27   { \
  28     0x00720665, 0x67EB, 0x4a99, {0xBA, 0xF7, 0xD3, 0xC3, 0x3A, 0x1C, 0x7C, 0xC9 } \
  29   }
  30
  31 #define EFI_TCP4_PROTOCOL_GUID \
  32   { \
  33     0x65530BC7, 0xA359, 0x410f, {0xB0, 0x10, 0x5A, 0xAD, 0xC7, 0xEC, 0x2B, 0x62 } \
  34   }
  35
  36 typedef struct _EFI_TCP4_PROTOCOL EFI_TCP4_PROTOCOL;
  37
  38 typedef struct {
  39   EFI_HANDLE              InstanceHandle;
  40   EFI_IPv4_ADDRESS        LocalAddress;
  41   UINT16                  LocalPort;
  42   EFI_IPv4_ADDRESS        RemoteAddress;
  43   UINT16                  RemotePort;
  44 } EFI_TCP4_SERVICE_POINT;
  45
  46 typedef struct {
  47   EFI_HANDLE              DriverHandle;
  48   UINT32                  ServiceCount;
  49   EFI_TCP4_SERVICE_POINT  Services[1];
  50 } EFI_TCP4_VARIABLE_DATA;
  51
  52 typedef struct {
  53   BOOLEAN                 UseDefaultAddress;
  54   EFI_IPv4_ADDRESS        StationAddress;
  55   EFI_IPv4_ADDRESS        SubnetMask;
  56   UINT16                  StationPort;
  57   EFI_IPv4_ADDRESS        RemoteAddress;
  58   UINT16                  RemotePort;
  59   BOOLEAN                 ActiveFlag;
  60 } EFI_TCP4_ACCESS_POINT;
  61
  62 typedef struct {
  63   UINT32                  ReceiveBufferSize;
  64   UINT32                  SendBufferSize;
  65   UINT32                  MaxSynBackLog;
  66   UINT32                  ConnectionTimeout;
  67   UINT32                  DataRetries;
  68   UINT32                  FinTimeout;
  69   UINT32                  TimeWaitTimeout;
  70   UINT32                  KeepAliveProbes;
  71   UINT32                  KeepAliveTime;
  72   UINT32                  KeepAliveInterval;
  73   BOOLEAN                 EnableNagle;
  74   BOOLEAN                 EnableTimeStamp;
  75   BOOLEAN                 EnableWindowScaling;
  76   BOOLEAN                 EnableSelectiveAck;
  77   BOOLEAN                 EnablePathMtuDiscovery;
  78 } EFI_TCP4_OPTION;
  79
  80 typedef struct {
  81   //
  82   // I/O parameters
  83   //
  84   UINT8                   TypeOfService;
  85   UINT8                   TimeToLive;
  86
  87   //
  88   // Access Point
  89   //
  90   EFI_TCP4_ACCESS_POINT   AccessPoint;
  91
  92   //
  93   // TCP Control Options
  94   //
  95   EFI_TCP4_OPTION         *ControlOption;
  96 } EFI_TCP4_CONFIG_DATA;
  97
  98 ///
  99 /// TCP4 connnection state
 100 ///
 101 typedef enum {
 102   Tcp4StateClosed         = 0,
 103   Tcp4StateListen         = 1,
 104   Tcp4StateSynSent        = 2,
 105   Tcp4StateSynReceived    = 3,
 106   Tcp4StateEstablished    = 4,
 107   Tcp4StateFinWait1       = 5,
 108   Tcp4StateFinWait2       = 6,
 109   Tcp4StateClosing        = 7,
 110   Tcp4StateTimeWait       = 8,
 111   Tcp4StateCloseWait      = 9,
 112   Tcp4StateLastAck        = 10
 113 } EFI_TCP4_CONNECTION_STATE;
 114
 115 typedef struct {
 116   EFI_EVENT   Event;
 117   EFI_STATUS  Status;
 118 } EFI_TCP4_COMPLETION_TOKEN;
 119
 120 typedef struct {
 121   EFI_TCP4_COMPLETION_TOKEN CompletionToken;
 122 } EFI_TCP4_CONNECTION_TOKEN;
 123
 124 typedef struct {
 125   EFI_TCP4_COMPLETION_TOKEN CompletionToken;
 126   EFI_HANDLE                NewChildHandle;
 127 } EFI_TCP4_LISTEN_TOKEN;
 128
 129 typedef struct {
 130   UINT32 FragmentLength;
 131   VOID   *FragmentBuffer;
 132 } EFI_TCP4_FRAGMENT_DATA;
 133
 134 typedef struct {
 135   BOOLEAN                   UrgentFlag;
 136   UINT32                    DataLength;
 137   UINT32                    FragmentCount;
 138   EFI_TCP4_FRAGMENT_DATA    FragmentTable[1];
 139 } EFI_TCP4_RECEIVE_DATA;
 140
 141 typedef struct {
 142   BOOLEAN                   Push;
 143   BOOLEAN                   Urgent;
 144   UINT32                    DataLength;
 145   UINT32                    FragmentCount;
 146   EFI_TCP4_FRAGMENT_DATA    FragmentTable[1];
 147 } EFI_TCP4_TRANSMIT_DATA;
 148
 149 typedef struct {
 150   EFI_TCP4_COMPLETION_TOKEN CompletionToken;
 151   union {
 152     EFI_TCP4_RECEIVE_DATA   *RxData;
 153     EFI_TCP4_TRANSMIT_DATA  *TxData;
 154   } Packet;
 155 } EFI_TCP4_IO_TOKEN;
 156
 157 typedef struct {
 158   EFI_TCP4_COMPLETION_TOKEN CompletionToken;
 159   BOOLEAN                   AbortOnClose;
 160 } EFI_TCP4_CLOSE_TOKEN;
 161
 162 //
 163 // Interface definition for TCP4 protocol
 164 //
 165
 166 /**
 167   Get the current operational status.
 168
 169   @param  This           Pointer to the EFI_TCP4_PROTOCOL instance.
 170   @param  Tcp4State      Pointer to the buffer to receive the current TCP state.
 171   @param  Tcp4ConfigData Pointer to the buffer to receive the current TCP configuration.
 172   @param  Ip4ModeData    Pointer to the buffer to receive the current IPv4 configuration
 173                          data used by the TCPv4 instance.
 174   @param  MnpConfigData  Pointer to the buffer to receive the current MNP configuration
 175                          data used indirectly by the TCPv4 instance.
 176   @param  SnpModeData    Pointer to the buffer to receive the current SNP configuration
 177                          data used indirectly by the TCPv4 instance.
 178
 179   @retval EFI_SUCCESS           The mode data was read.
 180   @retval EFI_INVALID_PARAMETER This is NULL.
 181   @retval EFI_NOT_STARTED       No configuration data is available because this instance hasn't
 182                                  been started.
 183
 184 **/
 185 typedef
 186 EFI_STATUS
 187 (EFIAPI *EFI_TCP4_GET_MODE_DATA)(
 188   IN CONST  EFI_TCP4_PROTOCOL                  *This,
 189   OUT       EFI_TCP4_CONNECTION_STATE          *Tcp4State      OPTIONAL,
 190   OUT       EFI_TCP4_CONFIG_DATA               *Tcp4ConfigData OPTIONAL,
 191   OUT       EFI_IP4_MODE_DATA                  *Ip4ModeData    OPTIONAL,
 192   OUT       EFI_MANAGED_NETWORK_CONFIG_DATA    *MnpConfigData  OPTIONAL,
 193   OUT       EFI_SIMPLE_NETWORK_MODE            *SnpModeData    OPTIONAL
 194   );
 195
 196 /**
 197   Initialize or brutally reset the operational parameters for this EFI TCPv4 instance.
 198
 199   @param  This           Pointer to the EFI_TCP4_PROTOCOL instance.
 200   @param  Tcp4ConfigData Pointer to the configure data to configure the instance.
 201
 202   @retval EFI_SUCCESS           The operational settings are set, changed, or reset
 203                                 successfully.
 204   @retval EFI_INVALID_PARAMETER Some parameter is invalid.
 205   @retval EFI_NO_MAPPING        When using a default address, configuration (through
 206                                 DHCP, BOOTP, RARP, etc.) is not finished yet.
 207   @retval EFI_ACCESS_DENIED     Configuring TCP instance when it is configured without
 208                                 calling Configure() with NULL to reset it.
 209   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 210   @retval EFI_UNSUPPORTED       One or more of the control options are not supported in
 211                                 the implementation.
 212   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough system resources when
 213                                 executing Configure().
 214
 215 **/
 216 typedef
 217 EFI_STATUS
 218 (EFIAPI *EFI_TCP4_CONFIGURE)(
 219   IN EFI_TCP4_PROTOCOL                   *This,
 220   IN EFI_TCP4_CONFIG_DATA                *TcpConfigData OPTIONAL
 221   );
 222
 223
 224 /**
 225   Add or delete a route entry to the route table
 226
 227   @param  This           Pointer to the EFI_TCP4_PROTOCOL instance.
 228   @param  DeleteRoute    Set it to TRUE to delete this route from the routing table. Set it to
 229                          FALSE to add this route to the routing table.
 230                          DestinationAddress and SubnetMask are used as the
 231                          keywords to search route entry.
 232   @param  SubnetAddress  The destination network.
 233   @param  SubnetMask     The subnet mask of the destination network.
 234   @param  GatewayAddress The gateway address for this route. It must be on the same
 235                          subnet with the station address unless a direct route is specified.
 236
 237   @retval EFI_SUCCESS           The operation completed successfully.
 238   @retval EFI_NOT_STARTED       The EFI TCPv4 Protocol instance has not been configured.
 239   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 240                                 RARP, etc.) is not finished yet.
 241   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 242                                 - This is NULL.
 243                                 - SubnetAddress is NULL.
 244                                 - SubnetMask is NULL.
 245                                 - GatewayAddress is NULL.
 246                                 - *SubnetAddress is not NULL a valid subnet address.
 247                                 - *SubnetMask is not a valid subnet mask.
 248                                 - *GatewayAddress is not a valid unicast IP address or it
 249                                 is not in the same subnet.
 250   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough resources to add the entry to the
 251                                 routing table.
 252   @retval EFI_NOT_FOUND         This route is not in the routing table.
 253   @retval EFI_ACCESS_DENIED     The route is already defined in the routing table.
 254   @retval EFI_UNSUPPORTED       The TCP driver does not support this operation.
 255
 256 **/
 257 typedef
 258 EFI_STATUS
 259 (EFIAPI *EFI_TCP4_ROUTES)(
 260   IN EFI_TCP4_PROTOCOL                   *This,
 261   IN BOOLEAN                             DeleteRoute,
 262   IN EFI_IPv4_ADDRESS                    *SubnetAddress,
 263   IN EFI_IPv4_ADDRESS                    *SubnetMask,
 264   IN EFI_IPv4_ADDRESS                    *GatewayAddress
 265   );
 266
 267 /**
 268   Initiate a nonblocking TCP connection request for an active TCP instance.
 269
 270   @param  This                  Pointer to the EFI_TCP4_PROTOCOL instance.
 271   @param  ConnectionToken       Pointer to the connection token to return when the TCP three
 272                                 way handshake finishes.
 273
 274   @retval EFI_SUCCESS           The connection request is successfully initiated and the state
 275                                 of this TCPv4 instance has been changed to Tcp4StateSynSent.
 276   @retval EFI_NOT_STARTED       This EFI TCPv4 Protocol instance has not been configured.
 277   @retval EFI_ACCESS_DENIED     One or more of the following conditions are TRUE:
 278                                 - This instance is not configured as an active one.
 279                                 - This instance is not in Tcp4StateClosed state.
 280   @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
 281                                 - This is NULL.
 282                                 - ConnectionToken is NULL.
 283                                 - ConnectionToken->CompletionToken.Event is NULL.
 284   @retval EFI_OUT_OF_RESOURCES  The driver can't allocate enough resource to initiate the activ eopen.
 285   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 286
 287 **/
 288 typedef
 289 EFI_STATUS
 290 (EFIAPI *EFI_TCP4_CONNECT)(
 291   IN EFI_TCP4_PROTOCOL                   *This,
 292   IN EFI_TCP4_CONNECTION_TOKEN           *ConnectionToken
 293   );
 294
 295
 296 /**
 297   Listen on the passive instance to accept an incoming connection request. This is a nonblocking operation.
 298
 299   @param  This        Pointer to the EFI_TCP4_PROTOCOL instance.
 300   @param  ListenToken Pointer to the listen token to return when operation finishes.
 301
 302   @retval EFI_SUCCESS           The listen token has been queued successfully.
 303   @retval EFI_NOT_STARTED       This EFI TCPv4 Protocol instance has not been configured.
 304   @retval EFI_ACCESS_DENIED     One or more of the following are TRUE:
 305                                 - This instance is not a passive instance.
 306                                 - This instance is not in Tcp4StateListen state.
 307                                 - The same listen token has already existed in the listen
 308                                 token queue of this TCP instance.
 309   @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
 310                                 - This is NULL.
 311                                 - ListenToken is NULL.
 312                                 - ListentToken->CompletionToken.Event is NULL.
 313   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough resource to finish the operation.
 314   @retval EFI_DEVICE_ERROR      Any unexpected and not belonged to above category error.
 315
 316 **/
 317 typedef
 318 EFI_STATUS
 319 (EFIAPI *EFI_TCP4_ACCEPT)(
 320   IN EFI_TCP4_PROTOCOL                   *This,
 321   IN EFI_TCP4_LISTEN_TOKEN               *ListenToken
 322   );
 323
 324 /**
 325   Queues outgoing data into the transmit queue.
 326
 327   @param  This  Pointer to the EFI_TCP4_PROTOCOL instance.
 328   @param  Token Pointer to the completion token to queue to the transmit queue.
 329
 330   @retval EFI_SUCCESS             The data has been queued for transmission.
 331   @retval EFI_NOT_STARTED         This EFI TCPv4 Protocol instance has not been configured.
 332   @retval EFI_NO_MAPPING          When using a default address, configuration (DHCP, BOOTP,
 333                                   RARP, etc.) is not finished yet.
 334   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
 335                                   - This is NULL.
 336                                   - Token is NULL.
 337                                   - Token->CompletionToken.Event is NULL.
 338                                   - Token->Packet.TxData is NULL L.
 339                                   - Token->Packet.FragmentCount is zero.
 340                                   - Token->Packet.DataLength is not equal to the sum of fragment lengths.
 341   @retval EFI_ACCESS_DENIED       One or more of the following conditions is TRUE:
 342                                   - A transmit completion token with the same Token->CompletionToken.Event
 343                                   was already in the transmission queue.
 344                                   - The current instance is in Tcp4StateClosed state.
 345                                   - The current instance is a passive one and it is in
 346                                   Tcp4StateListen state.
 347                                   - User has called Close() to disconnect this connection.
 348   @retval EFI_NOT_READY           The completion token could not be queued because the
 349                                   transmit queue is full.
 350   @retval EFI_OUT_OF_RESOURCES    Could not queue the transmit data because of resource
 351                                   shortage.
 352   @retval EFI_NETWORK_UNREACHABLE There is no route to the destination network or address.
 353
 354 **/
 355 typedef
 356 EFI_STATUS
 357 (EFIAPI *EFI_TCP4_TRANSMIT)(
 358   IN EFI_TCP4_PROTOCOL                   *This,
 359   IN EFI_TCP4_IO_TOKEN                   *Token
 360   );
 361
 362
 363 /**
 364   Places an asynchronous receive request into the receiving queue.
 365
 366   @param  This  Pointer to the EFI_TCP4_PROTOCOL instance.
 367   @param  Token Pointer to a token that is associated with the receive data
 368                 descriptor.
 369
 370   @retval EFI_SUCCESS           The receive completion token was cached.
 371   @retval EFI_NOT_STARTED       This EFI TCPv4 Protocol instance has not been configured.
 372   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP, RARP,
 373                                 etc.) is not finished yet.
 374   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 375                                 - This is NULL.
 376                                 - Token is NULL.
 377                                 - Token->CompletionToken.Event is NULL.
 378                                 - Token->Packet.RxData is NULL.
 379                                 - Token->Packet.RxData->DataLength is 0.
 380                                 - The Token->Packet.RxData->DataLength is not
 381                                 the sum of all FragmentBuffer length in FragmentTable.
 382   @retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of
 383                                system resources (usually memory).
 384   @retval EFI_DEVICE_ERROR     An unexpected system or network error occurred.
 385   @retval EFI_ACCESS_DENIED    One or more of the following conditions is TRUE:
 386                                - A receive completion token with the same Token-
 387                                >CompletionToken.Event was already in the receive
 388                                queue.
 389                                - The current instance is in Tcp4StateClosed state.
 390                                - The current instance is a passive one and it is in
 391                                Tcp4StateListen state.
 392                                - User has called Close() to disconnect this connection.
 393   @retval EFI_CONNECTION_FIN   The communication peer has closed the connection and there is
 394                                no any buffered data in the receive buffer of this instance.
 395   @retval EFI_NOT_READY        The receive request could not be queued because the receive queue is full.
 396
 397 **/
 398 typedef
 399 EFI_STATUS
 400 (EFIAPI *EFI_TCP4_RECEIVE)(
 401   IN EFI_TCP4_PROTOCOL                   *This,
 402   IN EFI_TCP4_IO_TOKEN                   *Token
 403   );
 404
 405 /**
 406   Disconnecting a TCP connection gracefully or reset a TCP connection. This function is a
 407   nonblocking operation.
 408
 409   @param  This       Pointer to the EFI_TCP4_PROTOCOL instance.
 410   @param  CloseToken Pointer to the close token to return when operation finishes.
 411
 412   @retval EFI_SUCCESS           The Close() is called successfully.
 413   @retval EFI_NOT_STARTED       This EFI TCPv4 Protocol instance has not been configured.
 414   @retval EFI_ACCESS_DENIED     One or more of the following are TRUE:
 415                                 - Configure() has been called with
 416                                 TcpConfigData set to NULL and this function has
 417                                 not returned.
 418                                 - Previous Close() call on this instance has not
 419                                 finished.
 420   @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
 421                                 - This is NULL.
 422                                 - CloseToken is NULL.
 423                                 - CloseToken->CompletionToken.Event is NULL.
 424   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough resource to finish the operation.
 425   @retval EFI_DEVICE_ERROR      Any unexpected and not belonged to above category error.
 426
 427 **/
 428 typedef
 429 EFI_STATUS
 430 (EFIAPI *EFI_TCP4_CLOSE)(
 431   IN EFI_TCP4_PROTOCOL                   *This,
 432   IN EFI_TCP4_CLOSE_TOKEN                *CloseToken
 433   );
 434
 435 /**
 436   Abort an asynchronous connection, listen, transmission or receive request.
 437
 438   @param  This  Pointer to the EFI_TCP4_PROTOCOL instance.
 439   @param  Token Pointer to a token that has been issued by
 440                 EFI_TCP4_PROTOCOL.Connect(),
 441                 EFI_TCP4_PROTOCOL.Accept(),
 442                 EFI_TCP4_PROTOCOL.Transmit() or
 443                 EFI_TCP4_PROTOCOL.Receive(). If NULL, all pending
 444                 tokens issued by above four functions will be aborted. Type
 445                 EFI_TCP4_COMPLETION_TOKEN is defined in
 446                 EFI_TCP4_PROTOCOL.Connect().
 447
 448   @retval  EFI_SUCCESS             The asynchronous I/O request is aborted and Token->Event
 449                                    is signaled.
 450   @retval  EFI_INVALID_PARAMETER   This is NULL.
 451   @retval  EFI_NOT_STARTED         This instance hasn't been configured.
 452   @retval  EFI_NO_MAPPING          When using the default address, configuration
 453                                    (DHCP, BOOTP,RARP, etc.) hasn't finished yet.
 454   @retval  EFI_NOT_FOUND           The asynchronous I/O request isn't found in the
 455                                    transmission or receive queue. It has either
 456                                    completed or wasn't issued by Transmit() and Receive().
 457
 458 **/
 459 typedef
 460 EFI_STATUS
 461 (EFIAPI *EFI_TCP4_CANCEL)(
 462   IN EFI_TCP4_PROTOCOL                   *This,
 463   IN EFI_TCP4_COMPLETION_TOKEN           *Token OPTIONAL
 464   );
 465
 466
 467 /**
 468   Poll to receive incoming data and transmit outgoing segments.
 469
 470   @param  This Pointer to the EFI_TCP4_PROTOCOL instance.
 471
 472   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
 473   @retval  EFI_INVALID_PARAMETER This is NULL.
 474   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 475   @retval  EFI_NOT_READY         No incoming or outgoing data is processed.
 476   @retval  EFI_TIMEOUT           Data was dropped out of the transmission or receive queue.
 477                                  Consider increasing the polling rate.
 478
 479 **/
 480 typedef
 481 EFI_STATUS
 482 (EFIAPI *EFI_TCP4_POLL)(
 483   IN EFI_TCP4_PROTOCOL                   *This
 484   );
 485
 486 ///
 487 /// The EFI_TCP4_PROTOCOL defines the EFI TCPv4 Protocol child to be used by
 488 /// any network drivers or applications to send or receive data stream.
 489 /// It can either listen on a specified port as a service or actively connected
 490 /// to remote peer as a client. Each instance has its own independent settings,
 491 /// such as the routing table.
 492 ///
 493 struct _EFI_TCP4_PROTOCOL {
 494   EFI_TCP4_GET_MODE_DATA                 GetModeData;
 495   EFI_TCP4_CONFIGURE                     Configure;
 496   EFI_TCP4_ROUTES                        Routes;
 497   EFI_TCP4_CONNECT                       Connect;
 498   EFI_TCP4_ACCEPT                        Accept;
 499   EFI_TCP4_TRANSMIT                      Transmit;
 500   EFI_TCP4_RECEIVE                       Receive;
 501   EFI_TCP4_CLOSE                         Close;
 502   EFI_TCP4_CANCEL                        Cancel;
 503   EFI_TCP4_POLL                          Poll;
 504 };
 505
 506 extern EFI_GUID gEfiTcp4ServiceBindingProtocolGuid;
 507 extern EFI_GUID gEfiTcp4ProtocolGuid;
 508
 509 #endif