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 - 2008, 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 **/
  17
  18 #ifndef __DEBUG_PORT_H__
  19 #define __DEBUG_PORT_H__
  20
  21
  22 //
  23 // DebugPortIo protocol {EBA4E8D2-3858-41EC-A281-2647BA9660D0}
  24 //
  25 #define EFI_DEBUGPORT_PROTOCOL_GUID \
  26   { \
  27     0xEBA4E8D2, 0x3858, 0x41EC, {0xA2, 0x81, 0x26, 0x47, 0xBA, 0x96, 0x60, 0xD0 } \
  28   }
  29
  30 extern EFI_GUID gEfiDebugPortProtocolGuid;
  31
  32 typedef struct _EFI_DEBUGPORT_PROTOCOL EFI_DEBUGPORT_PROTOCOL;
  33
  34 //
  35 // DebugPort member functions
  36 //
  37
  38 /**
  39   Resets the debugport.
  40
  41   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
  42
  43   @retval EFI_SUCCESS           The debugport device was reset and is in usable state.
  44   @retval EFI_DEVICE_ERROR      The debugport device could not be reset and is unusable.
  45
  46 **/
  47 typedef
  48 EFI_STATUS
  49 (EFIAPI *EFI_DEBUGPORT_RESET)(
  50   IN EFI_DEBUGPORT_PROTOCOL               *This
  51   );
  52
  53 /**
  54   Writes data to the debugport.
  55
  56   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
  57   @param  Timeout               The number of microseconds to wait before timing out a write operation.
  58   @param  BufferSize            On input, the requested number of bytes of data to write. On output, the
  59                                 number of bytes of data actually written.
  60   @param  Buffer                A pointer to a buffer containing the data to write.
  61
  62   @retval EFI_SUCCESS           The data was written.
  63   @retval EFI_DEVICE_ERROR      The device reported an error.
  64   @retval EFI_TIMEOUT           The data write was stopped due to a timeout.
  65
  66 **/
  67 typedef
  68 EFI_STATUS
  69 (EFIAPI *EFI_DEBUGPORT_WRITE)(
  70   IN EFI_DEBUGPORT_PROTOCOL               *This,
  71   IN UINT32                               Timeout,
  72   IN OUT UINTN                            *BufferSize,
  73   IN VOID                                 *Buffer
  74   );
  75
  76 /**
  77   Reads data from the debugport.
  78
  79   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
  80   @param  Timeout               The number of microseconds to wait before timing out a read operation.
  81   @param  BufferSize            On input, the requested number of bytes of data to read. On output, the
  82                                 number of bytes of data actually number of bytes
  83                                 of data read and returned in Buffer.
  84   @param  Buffer                A pointer to a buffer into which the data read will be saved.
  85
  86   @retval EFI_SUCCESS           The data was read.
  87   @retval EFI_DEVICE_ERROR      The device reported an error.
  88   @retval EFI_TIMEOUT           The operation was stopped due to a timeout or overrun.
  89
  90 **/
  91 typedef
  92 EFI_STATUS
  93 (EFIAPI *EFI_DEBUGPORT_READ)(
  94   IN EFI_DEBUGPORT_PROTOCOL               *This,
  95   IN UINT32                               Timeout,
  96   IN OUT UINTN                            *BufferSize,
  97   OUT VOID                                *Buffer
  98   );
  99
 100 /**
 101   Checks to see if any data is available to be read from the debugport device.
 102
 103   @param  This                  A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
 104
 105   @retval EFI_SUCCESS           At least one byte of data is available to be read.
 106   @retval EFI_DEVICE_ERROR      The debugport device is not functioning correctly.
 107   @retval EFI_NOT_READY         No data is available to be read.
 108
 109 **/
 110 typedef
 111 EFI_STATUS
 112 (EFIAPI *EFI_DEBUGPORT_POLL)(
 113   IN EFI_DEBUGPORT_PROTOCOL               *This
 114   );
 115
 116 //
 117 // DebugPort protocol definition
 118 //
 119 /**
 120   @par Protocol Description:
 121   This protocol provides the communication link between the debug agent and the remote host.
 122
 123   @param Reset
 124   Resets the debugport hardware.
 125
 126   @param Write
 127   Send a buffer of characters to the debugport device.
 128
 129   @param Read
 130   Receive a buffer of characters from the debugport device.
 131
 132   @param Poll
 133   Determine if there is any data available to be read from the debugport device.
 134 **/
 135 struct _EFI_DEBUGPORT_PROTOCOL {
 136   EFI_DEBUGPORT_RESET Reset;
 137   EFI_DEBUGPORT_WRITE Write;
 138   EFI_DEBUGPORT_READ  Read;
 139   EFI_DEBUGPORT_POLL  Poll;
 140 };
 141
 142 //
 143 // DEBUGPORT variable definitions...
 144 //
 145 #define EFI_DEBUGPORT_VARIABLE_NAME L"DEBUGPORT"
 146 #define EFI_DEBUGPORT_VARIABLE_GUID EFI_DEBUGPORT_PROTOCOL_GUID
 147 #define gEfiDebugPortVariableGuid   gEfiDebugPortProtocolGuid
 148
 149 //
 150 // DebugPort device path definitions...
 151 //
 152 #define DEVICE_PATH_MESSAGING_DEBUGPORT EFI_DEBUGPORT_PROTOCOL_GUID
 153 #define gEfiDebugPortDevicePathGuid     gEfiDebugPortProtocolGuid
 154
 155 typedef struct {
 156   EFI_DEVICE_PATH_PROTOCOL  Header;
 157   EFI_GUID                  Guid;
 158 } DEBUGPORT_DEVICE_PATH;
 159
 160 #endif