AndroidFastbootTransport.h 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. /** @file
  2. Copyright (c) 2014, ARM Ltd. All rights reserved.<BR>
  3. SPDX-License-Identifier: BSD-2-Clause-Patent
  4. **/
  5. /*
  6. Transport protocol over which Android Fastboot transactions can be made.
  7. Fastboot is designed for USB, but this protocol is intended as an abstraction
  8. so that it can be implemented over any transport mechanism.
  9. */
  10. #ifndef __ANDROID_FASTBOOT_TRANSPORT_H__
  11. #define __ANDROID_FASTBOOT_TRANSPORT_H__
  12. extern EFI_GUID gAndroidFastbootTransportProtocolGuid;
  13. /*
  14. Set up the transport system for use by Fastboot.
  15. e.g. For USB this probably means making the device enumerable. For TCP,
  16. preparing to accept incoming connections.
  17. It is _not_ the responsibility of this protocol's implementer to unite the
  18. data phase into a single buffer - that is handled by the Fastboot UEFI
  19. application. As the Fastboot protocol spec says: "Short packets are always
  20. acceptable and zero-length packets are ignored."
  21. However the commands and responses must be in a single packet, and the order
  22. of the packets must of course be maintained.
  23. If there is a fatal error in the receive channel, ReceiveEvent will be
  24. signalled, and a subsequent call to Receive() will return an error. This
  25. allows data transported prior to the error to be received.
  26. @param[in] ReceiveEvent Event to be Signalled when a packet has been received
  27. and is ready to be retrieved via Receive().
  28. @retval EFI_SUCCESS Initialised successfully.
  29. @retval EFI_DEVICE_ERROR Error in initialising hardware
  30. @retval (other) Error return from LocateProtocol functions.
  31. */
  32. typedef
  33. EFI_STATUS
  34. (*FASTBOOT_TRANSPORT_START) (
  35. IN EFI_EVENT ReceiveEvent
  36. );
  37. /*
  38. Function to be called when all Fastboot transactions are finished, to
  39. de-initialise the transport system.
  40. e.g. A USB OTG system might want to get out of peripheral mode so it can be
  41. a USB host.
  42. Note that this function will be called after an error is reported by Send or
  43. Receive
  44. @retval EFI_SUCCESS De-initialised successfully.
  45. @retval EFI_DEVICE_ERROR Error de-initialising hardware.
  46. */
  47. typedef
  48. EFI_STATUS
  49. (*FASTBOOT_TRANSPORT_STOP) (
  50. VOID
  51. );
  52. /*
  53. Send data. This function can be used both for command responses like "OKAY"
  54. and for the data phase (the protocol doesn't describe any situation when the
  55. latter might be necessary, but does allow it)
  56. Transmission need not finish before the function returns.
  57. If there is an error in transmission from which the transport system cannot
  58. recover, FatalErrorEvent will be signalled. Otherwise, it is assumed that all
  59. data was delivered successfully.
  60. @param[in] BufferSize Size in bytes of data to send.
  61. @param[in] Buffer Data to send.
  62. @param[in] FatalErrorEvent Event to signal if there was an error in
  63. transmission from which the transport system
  64. cannot recover.
  65. @retval EFI_SUCCESS The data was sent or queued for send.
  66. @retval EFI_DEVICE_ERROR There was an error preparing to send the data.
  67. */
  68. typedef
  69. EFI_STATUS
  70. (*FASTBOOT_TRANSPORT_SEND) (
  71. IN UINTN BufferSize,
  72. IN CONST VOID *Buffer,
  73. IN EFI_EVENT *FatalErrorEvent
  74. );
  75. /*
  76. When the event has been Signalled to say data is available from the host,
  77. this function is used to get data. In order to handle the case where several
  78. packets are received before ReceiveEvent's notify function is called, packets
  79. received are queued, and each call to this function returns the next packet in
  80. the queue. It should therefore be called in a loop, the exit condition being a
  81. return of EFI_NOT_READY.
  82. @param[out] Buffer Pointer to received data. Callee allocated - the
  83. caller must free it with FreePool.
  84. @param[out] BufferSize The size of received data in bytes
  85. @retval EFI_NOT_READY There is no data available
  86. @retval EFI_DEVICE_ERROR There was a fatal error in the receive channel.
  87. e.g. for USB the cable was unplugged or for TCP the
  88. connection was closed by the remote host..
  89. */
  90. typedef
  91. EFI_STATUS
  92. (*FASTBOOT_TRANSPORT_RECEIVE) (
  93. OUT UINTN *BufferSize,
  94. OUT VOID **Buffer
  95. );
  96. typedef struct _FASTBOOT_TRANSPORT_PROTOCOL {
  97. FASTBOOT_TRANSPORT_START Start;
  98. FASTBOOT_TRANSPORT_STOP Stop;
  99. FASTBOOT_TRANSPORT_SEND Send;
  100. FASTBOOT_TRANSPORT_RECEIVE Receive;
  101. } FASTBOOT_TRANSPORT_PROTOCOL;
  102. #endif