EmbeddedPkg: Fix various typos

[mirror_edk2.git] / EmbeddedPkg / GdbStub / SerialIo.c

/** @file\r
  Serial IO Abstraction for GDB stub. This allows an EFI consoles that shows up on the system\r
  running GDB. One console for error information and another console for user input/output.\r
\r
  Basic packet format is $packet-data#checksum. So every command has 4 bytes of overhead: $,\r
  #, 0, 0. The 0 and 0 are the ascii characters for the checksum.\r
\r
\r
  Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include <GdbStubInternal.h>\r
\r
//\r
// Set TRUE if F Reply package signals a ctrl-c. We can not process the Ctrl-c\r
// here we need to wait for the periodic callback to do this.\r
//\r
BOOLEAN gCtrlCBreakFlag = FALSE;\r
\r
//\r
// If the periodic callback is called while we are processing an F packet we need\r
// to let the callback know to not read from the serial stream as it could steal\r
// characters from the F response packet\r
//\r
BOOLEAN gProcessingFPacket = FALSE;\r
\r
/**\r
  Process a control-C break message.\r
\r
  Currently a place holder, remove the ASSERT when it gets implemented.\r
\r
  @param  ErrNo   Error information from the F reply packet or other source\r
\r
**/\r
\r
VOID\r
GdbCtrlCBreakMessage (\r
  IN  UINTN ErrNo\r
  )\r
{\r
  // See D.10.5 of gdb.pdf\r
  // This should look like a break message. Should look like SIGINT\r
\r
  /* TODO: Make sure if we should do anything with ErrNo */\r
  //Turn on the global Ctrl-C flag.\r
  gCtrlCBreakFlag = TRUE;\r
}\r
\r
\r
/**\r
  Parse the F reply packet and extract the return value and an ErrNo if it exists.\r
\r
  @param  Packet  Packet to parse like an F reply packet\r
  @param  ErrNo   Buffer to hold Count bytes that were read\r
\r
  @retval -1      Error, not a valid F reply packet\r
  @retval other   Return the return code from the F reply packet\r
\r
**/\r
INTN\r
GdbParseFReplyPacket (\r
  IN  CHAR8   *Packet,\r
  OUT UINTN   *ErrNo\r
  )\r
{\r
  INTN   RetCode;\r
\r
  if (Packet[0] != 'F') {\r
    // A valid response would be an F packet\r
    return -1;\r
  }\r
\r
  RetCode = AsciiStrHexToUintn (&Packet[1]);\r
\r
  // Find 1st comma\r
  for (;*Packet != '\0' && *Packet != ',';  Packet++);\r
  if (*Packet == '\0') {\r
    *ErrNo = 0;\r
    return RetCode;\r
  }\r
\r
  *ErrNo = AsciiStrHexToUintn (++Packet);\r
\r
  // Find 2nd comma\r
  for (;*Packet != '\0' && *Packet != ',';  Packet++);\r
  if (*Packet == '\0') {\r
    return RetCode;\r
  }\r
\r
  if (*(++Packet) == 'C') {\r
    GdbCtrlCBreakMessage (*ErrNo);\r
  }\r
\r
  return RetCode;\r
}\r
\r
\r
/**\r
  Read data from a FileDescriptor. On success number of bytes read is returned. Zero indicates\r
  the end of a file. On error -1 is returned. If count is zero, GdbRead returns zero.\r
\r
  @param  FileDescriptor   Device to talk to.\r
  @param  Buffer           Buffer to hold Count bytes that were read\r
  @param  Count            Number of bytes to transfer.\r
\r
  @retval -1               Error\r
  @retval {other}          Number of bytes read.\r
\r
**/\r
INTN\r
GdbRead (\r
  IN  INTN    FileDescriptor,\r
  OUT VOID    *Buffer,\r
  IN  UINTN   Count\r
  )\r
{\r
  CHAR8   Packet[128];\r
  UINTN   Size;\r
  INTN    RetCode;\r
  UINTN   ErrNo;\r
  BOOLEAN ReceiveDone = FALSE;\r
\r
  // Send:\r
  // "Fread,XX,YYYYYYYY,XX\r
  //\r
  // XX - FileDescriptor in ASCII\r
  // YYYYYYYY - Buffer address in ASCII\r
  // XX - Count in ASCII\r
  // SS - check sum\r
  //\r
  Size = AsciiSPrint (Packet, sizeof (Packet), "Fread,%x,%x,%x", FileDescriptor, Buffer, Count);\r
  // Packet array is too small if you got this ASSERT\r
  ASSERT (Size < sizeof (Packet));\r
\r
  gProcessingFPacket = TRUE;\r
  SendPacket (Packet);\r
  Print ((CHAR16 *)L"Packet sent..\n");\r
\r
  do {\r
    // Reply:\r
    ReceivePacket (Packet, sizeof (Packet));\r
    Print ((CHAR16 *)L"Command received..%c\n", Packet[0]);\r
\r
    // Process GDB commands\r
    switch (Packet[0]) {\r
      //Write memory command.\r
      //M addr,length:XX...\r
      case    'M':\r
        WriteToMemory (Packet);\r
        break;\r
\r
      //Fretcode, errno, Ctrl-C flag\r
      //retcode - Count read\r
      case    'F':\r
        //Once target receives F reply packet that means the previous\r
        //transactions are finished.\r
        ReceiveDone = TRUE;\r
        break;\r
\r
      //Send empty buffer\r
      default    :\r
        SendNotSupported();\r
        break;\r
    }\r
  } while (ReceiveDone == FALSE);\r
\r
  RetCode = GdbParseFReplyPacket (Packet, &ErrNo);\r
  Print ((CHAR16 *)L"RetCode: %x..ErrNo: %x..\n", RetCode, ErrNo);\r
\r
  if (ErrNo > 0) {\r
    //Send error to the host if there is any.\r
    SendError ((UINT8)ErrNo);\r
  }\r
\r
  gProcessingFPacket = FALSE;\r
\r
  return RetCode;\r
}\r
\r
\r
/**\r
  Write data to a FileDescriptor. On success number of bytes written is returned. Zero indicates\r
  nothing was written. On error -1 is returned.\r
\r
  @param  FileDescriptor   Device to talk to.\r
  @param  Buffer           Buffer to hold Count bytes that are to be written\r
  @param  Count            Number of bytes to transfer.\r
\r
  @retval -1               Error\r
  @retval {other}          Number of bytes written.\r
\r
**/\r
INTN\r
GdbWrite (\r
  IN  INTN          FileDescriptor,\r
  OUT CONST VOID    *Buffer,\r
  IN  UINTN         Count\r
  )\r
{\r
  CHAR8   Packet[128];\r
  UINTN   Size;\r
  INTN    RetCode;\r
  UINTN   ErrNo;\r
  BOOLEAN ReceiveDone = FALSE;\r
\r
  // Send:\r
  // #Fwrite,XX,YYYYYYYY,XX$SS\r
  //\r
  // XX - FileDescriptor in ASCII\r
  // YYYYYYYY - Buffer address in ASCII\r
  // XX - Count in ASCII\r
  // SS - check sum\r
  //\r
  Size = AsciiSPrint (Packet, sizeof (Packet), "Fwrite,%x,%x,%x", FileDescriptor, Buffer, Count);\r
  // Packet array is too small if you got this ASSERT\r
  ASSERT (Size < sizeof (Packet));\r
\r
  SendPacket (Packet);\r
  Print ((CHAR16 *)L"Packet sent..\n");\r
\r
  do {\r
    // Reply:\r
    ReceivePacket (Packet, sizeof (Packet));\r
    Print ((CHAR16 *)L"Command received..%c\n", Packet[0]);\r
\r
    // Process GDB commands\r
    switch (Packet[0]) {\r
      //Read memory command.\r
      //m addr,length.\r
      case    'm':\r
        ReadFromMemory (Packet);\r
        break;\r
\r
      //Fretcode, errno, Ctrl-C flag\r
      //retcode - Count read\r
      case    'F':\r
        //Once target receives F reply packet that means the previous\r
        //transactions are finished.\r
        ReceiveDone = TRUE;\r
        break;\r
\r
      //Send empty buffer\r
      default    :\r
        SendNotSupported();\r
        break;\r
    }\r
  } while (ReceiveDone == FALSE);\r
\r
  RetCode = GdbParseFReplyPacket (Packet, &ErrNo);\r
  Print ((CHAR16 *)L"RetCode: %x..ErrNo: %x..\n", RetCode, ErrNo);\r
\r
  //Send error to the host if there is any.\r
  if (ErrNo > 0) {\r
    SendError((UINT8)ErrNo);\r
  }\r
\r
  return RetCode;\r
}\r
\r
\r
/**\r
  Reset the serial device.\r
\r
  @param  This              Protocol instance pointer.\r
\r
  @retval EFI_SUCCESS       The device was reset.\r
  @retval EFI_DEVICE_ERROR  The serial device could not be reset.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GdbSerialReset (\r
  IN EFI_SERIAL_IO_PROTOCOL  *This\r
  )\r
{\r
  return EFI_SUCCESS;\r
}\r
\r
\r
/**\r
  Sets the baud rate, receive FIFO depth, transmit/receive time out, parity,\r
  data buts, and stop bits on a serial device.\r
\r
  @param  This             Protocol instance pointer.\r
  @param  BaudRate         The requested baud rate. A BaudRate value of 0 will use the the\r
                           device's default interface speed.\r
  @param  ReceiveFifoDepth The requested depth of the FIFO on the receive side of the\r
                           serial interface. A ReceiveFifoDepth value of 0 will use\r
                           the device's default FIFO depth.\r
  @param  Timeout          The requested time out for a single character in microseconds.\r
                           This timeout applies to both the transmit and receive side of the\r
                           interface. A Timeout value of 0 will use the device's default time\r
                           out value.\r
  @param  Parity           The type of parity to use on this serial device. A Parity value of\r
                           DefaultParity will use the device's default parity value.\r
  @param  DataBits         The number of data bits to use on the serial device. A DataBits\r
                           value of 0 will use the device's default data bit setting.\r
  @param  StopBits         The number of stop bits to use on this serial device. A StopBits\r
                           value of DefaultStopBits will use the device's default number of\r
                           stop bits.\r
\r
  @retval EFI_SUCCESS      The device was reset.\r
  @retval EFI_DEVICE_ERROR The serial device could not be reset.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GdbSerialSetAttributes (\r
  IN EFI_SERIAL_IO_PROTOCOL  *This,\r
  IN UINT64                  BaudRate,\r
  IN UINT32                  ReceiveFifoDepth,\r
  IN UINT32                  Timeout,\r
  IN EFI_PARITY_TYPE         Parity,\r
  IN UINT8                   DataBits,\r
  IN EFI_STOP_BITS_TYPE      StopBits\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
\r
/**\r
  Set the control bits on a serial device\r
\r
  @param  This             Protocol instance pointer.\r
  @param  Control          Set the bits of Control that are settable.\r
\r
  @retval EFI_SUCCESS      The new control bits were set on the serial device.\r
  @retval EFI_UNSUPPORTED  The serial device does not support this operation.\r
  @retval EFI_DEVICE_ERROR The serial device is not functioning correctly.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GdbSerialSetControl (\r
  IN EFI_SERIAL_IO_PROTOCOL  *This,\r
  IN UINT32                  Control\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
\r
/**\r
  Retrieves the status of the control bits on a serial device\r
\r
  @param  This              Protocol instance pointer.\r
  @param  Control           A pointer to return the current Control signals from the serial device.\r
\r
  @retval EFI_SUCCESS       The control bits were read from the serial device.\r
  @retval EFI_DEVICE_ERROR  The serial device is not functioning correctly.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GdbSerialGetControl (\r
  IN EFI_SERIAL_IO_PROTOCOL  *This,\r
  OUT UINT32                 *Control\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
\r
/**\r
  Writes data to a serial device.\r
\r
  @param  This              Protocol instance pointer.\r
  @param  BufferSize        On input, the size of the Buffer. On output, the amount of\r
                            data actually written.\r
  @param  Buffer            The buffer of data to write\r
\r
  @retval EFI_SUCCESS       The data was written.\r
  @retval EFI_DEVICE_ERROR  The device reported an error.\r
  @retval EFI_TIMEOUT       The data write was stopped due to a timeout.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GdbSerialWrite (\r
  IN EFI_SERIAL_IO_PROTOCOL  *This,\r
  IN OUT UINTN               *BufferSize,\r
  IN VOID                    *Buffer\r
  )\r
{\r
  GDB_SERIAL_DEV  *SerialDev;\r
  UINTN            Return;\r
\r
  SerialDev = GDB_SERIAL_DEV_FROM_THIS (This);\r
\r
  Return = GdbWrite (SerialDev->OutFileDescriptor, Buffer, *BufferSize);\r
  if (Return == (UINTN)-1) {\r
    return EFI_DEVICE_ERROR;\r
  }\r
\r
  if (Return != *BufferSize) {\r
    *BufferSize = Return;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  Writes data to a serial device.\r
\r
  @param  This              Protocol instance pointer.\r
  @param  BufferSize        On input, the size of the Buffer. On output, the amount of\r
                            data returned in Buffer.\r
  @param  Buffer            The buffer to return the data into.\r
\r
  @retval EFI_SUCCESS       The data was read.\r
  @retval EFI_DEVICE_ERROR  The device reported an error.\r
  @retval EFI_TIMEOUT       The data write was stopped due to a timeout.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
GdbSerialRead (\r
  IN EFI_SERIAL_IO_PROTOCOL  *This,\r
  IN OUT UINTN               *BufferSize,\r
  OUT VOID                   *Buffer\r
  )\r
{\r
  GDB_SERIAL_DEV  *SerialDev;\r
  UINTN            Return;\r
\r
  SerialDev = GDB_SERIAL_DEV_FROM_THIS (This);\r
\r
  Return = GdbRead (SerialDev->InFileDescriptor, Buffer, *BufferSize);\r
  if (Return == (UINTN)-1) {\r
    return EFI_DEVICE_ERROR;\r
  }\r
\r
  if (Return != *BufferSize) {\r
    *BufferSize = Return;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
\r
//\r
// Template used to initialize the GDB Serial IO protocols\r
//\r
GDB_SERIAL_DEV gdbSerialDevTemplate = {\r
  GDB_SERIAL_DEV_SIGNATURE,\r
  NULL,\r
\r
  { // SerialIo\r
    SERIAL_IO_INTERFACE_REVISION,\r
    GdbSerialReset,\r
    GdbSerialSetAttributes,\r
    GdbSerialSetControl,\r
    GdbSerialGetControl,\r
    GdbSerialWrite,\r
    GdbSerialRead,\r
    NULL\r
  },\r
  { // SerialMode\r
    0,      // ControlMask\r
    0,      // Timeout\r
    0,      // BaudRate\r
    1,      // RceiveFifoDepth\r
    0,      // DataBits\r
    0,      // Parity\r
    0       // StopBits\r
  },\r
  {\r
    {\r
      {\r
        HARDWARE_DEVICE_PATH,\r
        HW_VENDOR_DP,\r
        {\r
          (UINT8) (sizeof (VENDOR_DEVICE_PATH) + sizeof (UINT32)),\r
          (UINT8) ((sizeof (VENDOR_DEVICE_PATH) + sizeof (UINT32)) >> 8)\r
        },\r
      },\r
      EFI_SERIAL_IO_PROTOCOL_GUID\r
    },\r
    0,\r
    {\r
      END_DEVICE_PATH_TYPE,\r
      END_ENTIRE_DEVICE_PATH_SUBTYPE,\r
      {\r
        (UINT8) (sizeof (EFI_DEVICE_PATH_PROTOCOL)),\r
        (UINT8) (sizeof (EFI_DEVICE_PATH_PROTOCOL) >> 8)\r
      }\r
    },\r
  },\r
  GDB_STDIN,\r
  GDB_STDOUT\r
};\r
\r
\r
/**\r
  Make two serial consoles: 1) StdIn and StdOut via GDB. 2) StdErr via GDB.\r
\r
  These console show up on the remote system running GDB\r
\r
**/\r
VOID\r
GdbInitializeSerialConsole (\r
  VOID\r
  )\r
{\r
  EFI_STATUS      Status;\r
  GDB_SERIAL_DEV  *StdOutSerialDev;\r
  GDB_SERIAL_DEV  *StdErrSerialDev;\r
\r
  // Use the template to make a copy of the Serial Console private data structure.\r
  StdOutSerialDev = AllocateCopyPool (sizeof (GDB_SERIAL_DEV),  &gdbSerialDevTemplate);\r
  ASSERT (StdOutSerialDev != NULL);\r
\r
  // Fixup pointer after the copy\r
  StdOutSerialDev->SerialIo.Mode = &StdOutSerialDev->SerialMode;\r
\r
  StdErrSerialDev = AllocateCopyPool (sizeof (GDB_SERIAL_DEV),  &gdbSerialDevTemplate);\r
  ASSERT (StdErrSerialDev != NULL);\r
\r
  // Fixup pointer and modify stuff that is different for StdError\r
  StdErrSerialDev->SerialIo.Mode = &StdErrSerialDev->SerialMode;\r
  StdErrSerialDev->DevicePath.Index = 1;\r
  StdErrSerialDev->OutFileDescriptor = GDB_STDERR;\r
\r
  // Make a new handle with Serial IO protocol and its device path on it.\r
  Status = gBS->InstallMultipleProtocolInterfaces (\r
                  &StdOutSerialDev->Handle,\r
                  &gEfiSerialIoProtocolGuid,   &StdOutSerialDev->SerialIo,\r
                  &gEfiDevicePathProtocolGuid, &StdOutSerialDev->DevicePath,\r
                  NULL\r
                  );\r
  ASSERT_EFI_ERROR (Status);\r
\r
  // Make a new handle with Serial IO protocol and its device path on it.\r
  Status = gBS->InstallMultipleProtocolInterfaces (\r
                  &StdErrSerialDev->Handle,\r
                  &gEfiSerialIoProtocolGuid,   &StdErrSerialDev->SerialIo,\r
                  &gEfiDevicePathProtocolGuid, &StdErrSerialDev->DevicePath,\r
                  NULL\r
                  );\r
  ASSERT_EFI_ERROR (Status);\r
}\r
\r