MdePkg/Include/Protocol/Tcp4.h

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