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