MdePkg/Include/Protocol/Mtftp4.h

   1 /** @file
   2   EFI Multicast Trivial File Tranfer Protocol Definition
   3
   4   Copyright (c) 2006, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __EFI_MTFTP4_PROTOCOL_H__
  16 #define __EFI_MTFTP4_PROTOCOL_H__
  17
  18 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
  19   { \
  20     0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
  21   }
  22
  23 #define EFI_MTFTP4_PROTOCOL_GUID \
  24   { \
  25     0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
  26   }
  27
  28 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL;
  29 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN;
  30
  31 //
  32 //MTFTP4 packet opcode definition
  33 //
  34 #define EFI_MTFTP4_OPCODE_RRQ                     1
  35 #define EFI_MTFTP4_OPCODE_WRQ                     2
  36 #define EFI_MTFTP4_OPCODE_DATA                    3
  37 #define EFI_MTFTP4_OPCODE_ACK                     4
  38 #define EFI_MTFTP4_OPCODE_ERROR                   5
  39 #define EFI_MTFTP4_OPCODE_OACK                    6
  40 #define EFI_MTFTP4_OPCODE_DIR                     7
  41 #define EFI_MTFTP4_OPCODE_DATA8                   8
  42 #define EFI_MTFTP4_OPCODE_ACK8                    9
  43
  44 //
  45 // MTFTP4 error code definition
  46 //
  47 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED          0
  48 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND       1
  49 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION     2
  50 #define EFI_MTFTP4_ERRORCODE_DISK_FULL            3
  51 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION    4
  52 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID  5
  53 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS  6
  54 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER         7
  55 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED       8
  56
  57 //
  58 // MTFTP4 pacekt definitions
  59 //
  60 #pragma pack(1)
  61
  62 typedef struct {
  63   UINT16                  OpCode;
  64   UINT8                   Filename[1];
  65 } EFI_MTFTP4_REQ_HEADER;
  66
  67 typedef struct {
  68   UINT16                  OpCode;
  69   UINT8                   Data[1];
  70 } EFI_MTFTP4_OACK_HEADER;
  71
  72 typedef struct {
  73   UINT16                  OpCode;
  74   UINT16                  Block;
  75   UINT8                   Data[1];
  76 } EFI_MTFTP4_DATA_HEADER;
  77
  78 typedef struct {
  79   UINT16                  OpCode;
  80   UINT16                  Block[1];
  81 } EFI_MTFTP4_ACK_HEADER;
  82
  83 typedef struct {
  84   UINT16                  OpCode;
  85   UINT64                  Block;
  86   UINT8                   Data[1];
  87 } EFI_MTFTP4_DATA8_HEADER;
  88
  89 typedef struct {
  90   UINT16                  OpCode;
  91   UINT64                  Block[1];
  92 } EFI_MTFTP4_ACK8_HEADER;
  93
  94 typedef struct {
  95   UINT16                  OpCode;
  96   UINT16                  ErrorCode;
  97   UINT8                   ErrorMessage[1];
  98 } EFI_MTFTP4_ERROR_HEADER;
  99
 100 typedef union {
 101   UINT16                  OpCode;
 102   EFI_MTFTP4_REQ_HEADER   Rrq;
 103   EFI_MTFTP4_REQ_HEADER   Wrq;
 104   EFI_MTFTP4_OACK_HEADER  Oack;
 105   EFI_MTFTP4_DATA_HEADER  Data;
 106   EFI_MTFTP4_ACK_HEADER   Ack;
 107   EFI_MTFTP4_DATA8_HEADER Data8;
 108   EFI_MTFTP4_ACK8_HEADER  Ack8;
 109   EFI_MTFTP4_ERROR_HEADER Error;
 110 } EFI_MTFTP4_PACKET;
 111
 112 #pragma pack()
 113
 114 //
 115 // MTFTP4 option definition
 116 //
 117 typedef struct {
 118   UINT8                   *OptionStr;
 119   UINT8                   *ValueStr;
 120 } EFI_MTFTP4_OPTION;
 121
 122
 123 typedef struct {
 124   BOOLEAN                 UseDefaultSetting;
 125   EFI_IPv4_ADDRESS        StationIp;
 126   EFI_IPv4_ADDRESS        SubnetMask;
 127   UINT16                  LocalPort;
 128   EFI_IPv4_ADDRESS        GatewayIp;
 129   EFI_IPv4_ADDRESS        ServerIp;
 130   UINT16                  InitialServerPort;
 131   UINT16                  TryCount;
 132   UINT16                  TimeoutValue;
 133 } EFI_MTFTP4_CONFIG_DATA;
 134
 135
 136 typedef struct {
 137   EFI_MTFTP4_CONFIG_DATA  ConfigData;
 138   UINT8                   SupportedOptionCount;
 139   UINT8                   **SupportedOptoins;
 140   UINT8                   UnsupportedOptionCount;
 141   UINT8                   **UnsupportedOptoins;
 142 } EFI_MTFTP4_MODE_DATA;
 143
 144
 145 typedef struct {
 146   EFI_IPv4_ADDRESS        GatewayIp;
 147   EFI_IPv4_ADDRESS        ServerIp;
 148   UINT16                  ServerPort;
 149   UINT16                  TryCount;
 150   UINT16                  TimeoutValue;
 151 } EFI_MTFTP4_OVERRIDE_DATA;
 152
 153 //
 154 // Protocol interfaces definition
 155 //
 156
 157 /**
 158   a callback function that is provided by the caller to intercept
 159   the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
 160   EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
 161   EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
 162   EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
 163
 164   @param  This        Pointer to the EFI_MTFTP4_PROTOCOL instance.
 165   @param  Token       The token that the caller provided in the
 166                       EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
 167                       or ReadDirectory() function.
 168   @param  PacketLen   Indicates the length of the packet.
 169   @param  Packet      Pointer to an MTFTPv4 packet.
 170
 171   @retval EFI_SUCCESS Operation sucess
 172   @retval Others      Abort transfer process
 173
 174 **/
 175 typedef
 176 EFI_STATUS
 177 (EFIAPI *EFI_MTFTP4_CHECK_PACKET)(
 178   IN EFI_MTFTP4_PROTOCOL  *This,
 179   IN EFI_MTFTP4_TOKEN     *Token,
 180   IN UINT16               PacketLen,
 181   IN EFI_MTFTP4_PACKET    *Paket
 182   )
 183 ;
 184
 185 /**
 186   Timeout callback funtion.
 187
 188   @param  This           Pointer to the EFI_MTFTP4_PROTOCOL instance.
 189   @param  Token          The token that is provided in the
 190                          EFI_MTFTP4_PROTOCOL.ReadFile() or
 191                          EFI_MTFTP4_PROTOCOL.WriteFile() or
 192                          EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
 193                          by the caller.
 194
 195   @retval EFI_SUCCESS   Operation sucess
 196   @retval Others        Aborts download process.
 197
 198 **/
 199 typedef
 200 EFI_STATUS
 201 (EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)(
 202   IN EFI_MTFTP4_PROTOCOL  *This,
 203   IN EFI_MTFTP4_TOKEN     *Token
 204   )
 205 ;
 206
 207 /**
 208   a callback function that the caller provides to feed data to the
 209   EFI_MTFTP4_PROTOCOL.WriteFile() function.
 210
 211   @param  This   Pointer to the EFI_MTFTP4_PROTOCOL instance.
 212   @param  Token  The token provided in the
 213                  EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
 214   @param  Length Indicates the length of the raw data wanted on input, and the
 215                  length the data available on output.
 216   @param  Buffer Pointer to the buffer where the data is stored.
 217
 218   @retval EFI_SUCCESS Operation sucess
 219   @retval Others      Aborts session.
 220
 221 **/
 222 typedef
 223 EFI_STATUS
 224 (EFIAPI *EFI_MTFTP4_PACKET_NEEDED)(
 225   IN  EFI_MTFTP4_PROTOCOL *This,
 226   IN  EFI_MTFTP4_TOKEN    *Token,
 227   IN  OUT UINT16          *Length,
 228   OUT VOID                **Buffer
 229   )
 230 ;
 231
 232
 233 /**
 234   Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
 235
 236   @param  This     Pointer to the EFI_MTFTP4_PROTOCOL instance.
 237   @param  ModeData Pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
 238
 239   @retval EFI_SUCCESS           The configuration data was successfully returned.
 240   @retval EFI_OUT_OF_RESOURCES  The required mode data could not be allocated.
 241   @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
 242
 243 **/
 244 typedef
 245 EFI_STATUS
 246 (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(
 247   IN  EFI_MTFTP4_PROTOCOL     *This,
 248   OUT EFI_MTFTP4_MODE_DATA    *ModeData
 249   )
 250 ;
 251
 252
 253 /**
 254   Initializes, changes, or resets the default operational setting for this
 255   EFI MTFTPv4 Protocol driver instance.
 256
 257   @param  This            Pointer to the EFI_MTFTP4_PROTOCOL instance.
 258   @param  MtftpConfigData Pointer to the configuration data structure.
 259
 260   @retval EFI_SUCCESS           The EFI MTFTPv4 Protocol driver was configured successfully.
 261   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 262   @retval EFI_ACCESS_DENIED     The EFI configuration could not be changed at this time because
 263                                 there is one MTFTP background operation in progress.
 264   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 265                                 RARP, etc.) has not finished yet.
 266   @retval EFI_UNSUPPORTED       A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
 267                                 be located when clients choose to use the default address
 268                                 settings.
 269   @retval EFI_OUT_OF_RESOURCES  The EFI MTFTPv4 Protocol driver instance data could not be
 270                                 allocated.
 271   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI
 272                                  MTFTPv4 Protocol driver instance is not configured.
 273
 274 **/
 275 typedef
 276 EFI_STATUS
 277 (EFIAPI *EFI_MTFTP4_CONFIGURE)(
 278   IN EFI_MTFTP4_PROTOCOL       *This,
 279   IN EFI_MTFTP4_CONFIG_DATA    *MtftpConfigData OPTIONAL
 280   )
 281 ;
 282
 283
 284 /**
 285   Gets information about a file from an MTFTPv4 server.
 286
 287   @param  This         Pointer to the EFI_MTFTP4_PROTOCOL instance.
 288   @param  OverrideData Data that is used to override the existing parameters. If NULL,
 289                        the default parameters that were set in the
 290                        EFI_MTFTP4_PROTOCOL.Configure() function are used.
 291   @param  Filename     Pointer to ASCIIZ file name string.
 292   @param  ModeStr      Pointer to ASCIIZ mode string. If NULL, "octet" will be used.
 293   @param  OptionCount  Number of option/value string pairs in OptionList.
 294   @param  OptionList   Pointer to array of option/value string pairs. Ignored if
 295                        OptionCount is zero.
 296   @param  PacketLength The number of bytes in the returned packet.
 297   @param  Packet       The pointer to the received packet. This buffer must be freed by
 298                        the caller.
 299
 300   @retval EFI_SUCCESS           An MTFTPv4 OACK packet was received and is in the Buffer.
 301   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 302   @retval EFI_UNSUPPORTED       One or more options in the OptionList are in the
 303                                 unsupported list of structure EFI_MTFTP4_MODE_DATA.
 304   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
 305   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 306                                 RARP, etc.) has not finished yet.
 307   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
 308   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 309   @retval EFI_TFTP_ERROR        An MTFTPv4 ERROR packet was received and is in the buffer.
 310   @retval EFI_ICMP_ERROR        An ICMP ERROR packet was received and is in the Buffer.
 311   @retval EFI_PROTOCOL_ERROR    An unexpected MTFTPv4 packet was received and is in the buffer.
 312   @retval EFI_TIMEOUT           No responses were received from the MTFTPv4 server.
 313   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 314
 315 **/
 316 typedef
 317 EFI_STATUS
 318 (EFIAPI *EFI_MTFTP4_GET_INFO)(
 319   IN  EFI_MTFTP4_PROTOCOL      *This,
 320   IN  EFI_MTFTP4_OVERRIDE_DATA *OverrideData   OPTIONAL,
 321   IN  UINT8                    *Filename,
 322   IN  UINT8                    *ModeStr        OPTIONAL,
 323   IN  UINT8                    OptionCount,
 324   IN  EFI_MTFTP4_OPTION        *OptionList,
 325   OUT UINT32                   *PacketLength,
 326   OUT EFI_MTFTP4_PACKET        **Packet        OPTIONAL
 327   )
 328 ;
 329
 330 /**
 331   Parses the options in an MTFTPv4 OACK packet.
 332
 333   @param  This         Pointer to the EFI_MTFTP4_PROTOCOL instance.
 334   @param  PacketLen    Length of the OACK packet to be parsed.
 335   @param  Packet       Pointer to the OACK packet to be parsed.
 336   @param  OptionCount  Pointer to the number of options in following OptionList.
 337   @param  OptionList   Pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
 338                        Service FreePool() to release each option if they are not
 339                        needed any more.
 340
 341   @retval EFI_SUCCESS           The OACK packet was valid and the OptionCount and
 342                                 OptionList parameters have been updated.
 343   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 344                                 - PacketLen is 0.
 345                                 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
 346                                 - OptionCount is NULL.
 347   @retval EFI_NOT_FOUND         No options were found in the OACK packet.
 348   @retval EFI_OUT_OF_RESOURCES  Storage for the OptionList array cannot be allocated.
 349   @retval EFI_PROTOCOL_ERROR    One or more of the option fields is invalid.
 350
 351 **/
 352 typedef
 353 EFI_STATUS
 354 (EFIAPI *EFI_MTFTP4_PARSE_OPTIONS)(
 355   IN  EFI_MTFTP4_PROTOCOL      *This,
 356   IN  UINT32                   PacketLen,
 357   IN  EFI_MTFTP4_PACKET        *Packet,
 358   OUT UINT32                   *OptionCount,
 359   OUT EFI_MTFTP4_OPTION        **OptionList OPTIONAL
 360   )
 361 ;
 362
 363
 364 /**
 365   Downloads a file from an MTFTPv4 server.
 366
 367   @param  This  Pointer to the EFI_MTFTP4_PROTOCOL instance.
 368   @param  Token Pointer to the token structure to provide the parameters that are
 369                 used in this operation.
 370
 371   @retval EFI_SUCCESS          The data file has been transferred successfully.
 372   @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
 373   @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded data
 374                                in downloading process.
 375   @retval EFI_ABORTED          Current operation is aborted by user.
 376   @retval EFI_ICMP_ERROR       An ICMP ERROR packet was received.
 377   @retval EFI_TIMEOUT          No responses were received from the MTFTPv4 server.
 378   @retval EFI_TFTP_ERROR       An MTFTPv4 ERROR packet was received.
 379   @retval EFI_DEVICE_ERROR     An unexpected network error or system error occurred.
 380
 381 **/
 382 typedef
 383 EFI_STATUS
 384 (EFIAPI *EFI_MTFTP4_READ_FILE)(
 385   IN EFI_MTFTP4_PROTOCOL       *This,
 386   IN EFI_MTFTP4_TOKEN          *Token
 387   )
 388 ;
 389
 390
 391
 392 /**
 393   Sends a file to an MTFTPv4 server.
 394
 395   @param  This  Pointer to the EFI_MTFTP4_PROTOCOL instance.
 396   @param  Token Pointer to the token structure to provide the parameters that are
 397                 used in this operation.
 398
 399   @retval EFI_SUCCESS           The upload session has started.
 400   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
 401   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 402   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
 403                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
 404   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
 405   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 406                                 RARP, etc.) is not finished yet.
 407   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
 408   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 409   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
 410   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 411
 412 **/
 413 typedef
 414 EFI_STATUS
 415 (EFIAPI *EFI_MTFTP4_WRITE_FILE)(
 416   IN EFI_MTFTP4_PROTOCOL       *This,
 417   IN EFI_MTFTP4_TOKEN          *Token
 418   )
 419 ;
 420
 421
 422 /**
 423   Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
 424   implementations.
 425
 426   @param  This  Pointer to the EFI_MTFTP4_PROTOCOL instance.
 427   @param  Token Pointer to the token structure to provide the parameters that are
 428                 used in this operation.
 429
 430   @retval EFI_SUCCESS           The MTFTPv4 related file "directory" has been downloaded.
 431   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
 432   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 433   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
 434                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
 435   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
 436   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 437                                 RARP, etc.) is not finished yet.
 438   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
 439   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 440   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
 441   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 442
 443 **/
 444 typedef
 445 EFI_STATUS
 446 (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(
 447   IN EFI_MTFTP4_PROTOCOL       *This,
 448   IN EFI_MTFTP4_TOKEN          *Token
 449   )
 450 ;
 451
 452 /**
 453   Polls for incoming data packets and processes outgoing data packets.
 454
 455   @param  This Pointer to the EFI_MTFTP4_PROTOCOL instance.
 456
 457   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
 458   @retval  EFI_NOT_STARTED       This EFI MTFTPv4 Protocol instance has not been started.
 459   @retval  EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
 460                                  RARP, etc.) is not finished yet.
 461   @retval  EFI_INVALID_PARAMETER This is NULL.
 462   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 463   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
 464                                  Consider increasing the polling rate.
 465
 466 **/
 467 typedef
 468 EFI_STATUS
 469 (EFIAPI *EFI_MTFTP4_POLL) (
 470   IN EFI_MTFTP4_PROTOCOL       *This
 471   )
 472 ;
 473
 474
 475 struct _EFI_MTFTP4_PROTOCOL {
 476   EFI_MTFTP4_GET_MODE_DATA     GetModeData;
 477   EFI_MTFTP4_CONFIGURE         Configure;
 478   EFI_MTFTP4_GET_INFO          GetInfo;
 479   EFI_MTFTP4_PARSE_OPTIONS     ParseOptions;
 480   EFI_MTFTP4_READ_FILE         ReadFile;
 481   EFI_MTFTP4_WRITE_FILE        WriteFile;
 482   EFI_MTFTP4_READ_DIRECTORY    ReadDirectory;
 483   EFI_MTFTP4_POLL              Poll;
 484 };
 485
 486 struct _EFI_MTFTP4_TOKEN {
 487   OUT EFI_STATUS                  Status;
 488   IN  EFI_EVENT                   Event;
 489   IN  EFI_MTFTP4_OVERRIDE_DATA    *OverrideData;
 490   IN  UINT8                       *Filename;
 491   IN  UINT8                       *ModeStr;
 492   IN  UINT32                      OptionCount;
 493   IN  EFI_MTFTP4_OPTION           *OptionList;
 494   IN  OUT UINT64                  BufferSize;
 495   IN  OUT VOID                    *Buffer;
 496   IN  EFI_MTFTP4_CHECK_PACKET     CheckPacket;
 497   IN  EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;
 498   IN  EFI_MTFTP4_PACKET_NEEDED    PacketNeeded;
 499 };
 500
 501 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid;
 502 extern EFI_GUID gEfiMtftp4ProtocolGuid;
 503
 504 #endif
 505