MdePkg/Include/Protocol/DebugPort.h

   1 /** @file
   2
   3   The file defines the EFI Debugport protocol.
   4   This protocol is used by debug agent to communicate with the
   5   remote debug host.
   6
   7   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __DEBUG_PORT_H__
  13 #define __DEBUG_PORT_H__
  14
  15 ///
  16 /// DebugPortIo protocol {EBA4E8D2-3858-41EC-A281-2647BA9660D0}
  17 ///
  18 #define EFI_DEBUGPORT_PROTOCOL_GUID \
  19   { \
  20     0xEBA4E8D2, 0x3858, 0x41EC, {0xA2, 0x81, 0x26, 0x47, 0xBA, 0x96, 0x60, 0xD0 } \
  21   }
  22
  23 extern EFI_GUID  gEfiDebugPortProtocolGuid;
  24
  25 typedef struct _EFI_DEBUGPORT_PROTOCOL EFI_DEBUGPORT_PROTOCOL;
  26
  27 //
  28 // DebugPort member functions
  29 //
  30
  31 /**
  32   Resets the debugport.
  33
  34   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
  35
  36   @retval EFI_SUCCESS           The debugport device was reset and is in usable state.
  37   @retval EFI_DEVICE_ERROR      The debugport device could not be reset and is unusable.
  38
  39 **/
  40 typedef
  41 EFI_STATUS
  42 (EFIAPI *EFI_DEBUGPORT_RESET)(
  43   IN EFI_DEBUGPORT_PROTOCOL               *This
  44   );
  45
  46 /**
  47   Writes data to the debugport.
  48
  49   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
  50   @param  Timeout               The number of microseconds to wait before timing out a write operation.
  51   @param  BufferSize            On input, the requested number of bytes of data to write. On output, the
  52                                 number of bytes of data actually written.
  53   @param  Buffer                A pointer to a buffer containing the data to write.
  54
  55   @retval EFI_SUCCESS           The data was written.
  56   @retval EFI_DEVICE_ERROR      The device reported an error.
  57   @retval EFI_TIMEOUT           The data write was stopped due to a timeout.
  58
  59 **/
  60 typedef
  61 EFI_STATUS
  62 (EFIAPI *EFI_DEBUGPORT_WRITE)(
  63   IN EFI_DEBUGPORT_PROTOCOL               *This,
  64   IN UINT32                               Timeout,
  65   IN OUT UINTN                            *BufferSize,
  66   IN VOID                                 *Buffer
  67   );
  68
  69 /**
  70   Reads data from the debugport.
  71
  72   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
  73   @param  Timeout               The number of microseconds to wait before timing out a read operation.
  74   @param  BufferSize            On input, the requested number of bytes of data to read. On output, the
  75                                 number of bytes of data actually number of bytes
  76                                 of data read and returned in Buffer.
  77   @param  Buffer                A pointer to a buffer into which the data read will be saved.
  78
  79   @retval EFI_SUCCESS           The data was read.
  80   @retval EFI_DEVICE_ERROR      The device reported an error.
  81   @retval EFI_TIMEOUT           The operation was stopped due to a timeout or overrun.
  82
  83 **/
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *EFI_DEBUGPORT_READ)(
  87   IN EFI_DEBUGPORT_PROTOCOL               *This,
  88   IN UINT32                               Timeout,
  89   IN OUT UINTN                            *BufferSize,
  90   OUT VOID                                *Buffer
  91   );
  92
  93 /**
  94   Checks to see if any data is available to be read from the debugport device.
  95
  96   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
  97
  98   @retval EFI_SUCCESS           At least one byte of data is available to be read.
  99   @retval EFI_DEVICE_ERROR      The debugport device is not functioning correctly.
 100   @retval EFI_NOT_READY         No data is available to be read.
 101
 102 **/
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_DEBUGPORT_POLL)(
 106   IN EFI_DEBUGPORT_PROTOCOL               *This
 107   );
 108
 109 ///
 110 /// This protocol provides the communication link between the debug agent and the remote host.
 111 ///
 112 struct _EFI_DEBUGPORT_PROTOCOL {
 113   EFI_DEBUGPORT_RESET    Reset;
 114   EFI_DEBUGPORT_WRITE    Write;
 115   EFI_DEBUGPORT_READ     Read;
 116   EFI_DEBUGPORT_POLL     Poll;
 117 };
 118
 119 //
 120 // DEBUGPORT variable definitions...
 121 //
 122 #define EFI_DEBUGPORT_VARIABLE_NAME  L"DEBUGPORT"
 123 #define EFI_DEBUGPORT_VARIABLE_GUID  EFI_DEBUGPORT_PROTOCOL_GUID
 124
 125 extern EFI_GUID  gEfiDebugPortVariableGuid;
 126
 127 //
 128 // DebugPort device path definitions...
 129 //
 130 #define DEVICE_PATH_MESSAGING_DEBUGPORT  EFI_DEBUGPORT_PROTOCOL_GUID
 131
 132 extern EFI_GUID  gEfiDebugPortDevicePathGuid;
 133
 134 typedef struct {
 135   EFI_DEVICE_PATH_PROTOCOL    Header;
 136   EFI_GUID                    Guid;
 137 } DEBUGPORT_DEVICE_PATH;
 138
 139 #endif