SourceLevelDebugPkg: Change OPTIONAL keyword usage style

[mirror_edk2.git] / SourceLevelDebugPkg / Library / DebugAgent / DxeDebugAgent / DxeDebugAgentLib.c

/** @file\r
  Debug Agent library implementation for Dxe Core and Dxr modules.\r
\r
  Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include "DxeDebugAgentLib.h"\r
\r
DEBUG_AGENT_MAILBOX          mMailbox;\r
DEBUG_AGENT_MAILBOX          *mMailboxPointer = NULL;\r
IA32_IDT_GATE_DESCRIPTOR     mIdtEntryTable[33];\r
BOOLEAN                      mDxeCoreFlag                = FALSE;\r
BOOLEAN                      mMultiProcessorDebugSupport = FALSE;\r
VOID                         *mSavedIdtTable             = NULL;\r
UINTN                        mSaveIdtTableSize           = 0;\r
BOOLEAN                      mDebugAgentInitialized      = FALSE;\r
BOOLEAN                      mSkipBreakpoint             = FALSE;\r
\r
/**\r
  Check if debug agent support multi-processor.\r
\r
  @retval TRUE    Multi-processor is supported.\r
  @retval FALSE   Multi-processor is not supported.\r
\r
**/\r
BOOLEAN\r
MultiProcessorDebugSupport (\r
  VOID\r
  )\r
{\r
  return mMultiProcessorDebugSupport;\r
}\r
\r
/**\r
  Internal constructor worker function.\r
\r
  It will register one callback function on EFI PCD Protocol.\r
  It will allocate the NVS memory to store Mailbox and install configuration table\r
  in system table to store its pointer.\r
\r
**/\r
VOID\r
InternalConstructorWorker (\r
  VOID\r
  )\r
{\r
  EFI_STATUS                  Status;\r
  EFI_PHYSICAL_ADDRESS        Address;\r
  BOOLEAN                     DebugTimerInterruptState;\r
  DEBUG_AGENT_MAILBOX         *Mailbox;\r
  DEBUG_AGENT_MAILBOX         *NewMailbox;\r
  EFI_HOB_GUID_TYPE           *GuidHob;\r
  EFI_VECTOR_HANDOFF_INFO     *VectorHandoffInfo;\r
\r
  //\r
  // Check persisted vector handoff info\r
  //\r
  Status = EFI_SUCCESS;\r
  GuidHob = GetFirstGuidHob (&gEfiVectorHandoffInfoPpiGuid);\r
  if (GuidHob != NULL && !mDxeCoreFlag) {\r
    //\r
    // Check if configuration table is installed or not if GUIDed HOB existed,\r
    // only when Debug Agent is not linked by DXE Core\r
    //\r
    Status = EfiGetSystemConfigurationTable (&gEfiVectorHandoffTableGuid, (VOID **) &VectorHandoffInfo);\r
  }\r
  if (GuidHob == NULL || Status != EFI_SUCCESS) {\r
    //\r
    // Install configuration table for persisted vector handoff info if GUIDed HOB cannot be found or\r
    // configuration table does not exist\r
    //\r
    Status = gBS->InstallConfigurationTable (&gEfiVectorHandoffTableGuid, (VOID *) &mVectorHandoffInfoDebugAgent[0]);\r
    if (EFI_ERROR (Status)) {\r
      DEBUG ((DEBUG_ERROR, "DebugAgent: Cannot install configuration table for persisted vector handoff info!\n"));\r
      CpuDeadLoop ();\r
    }\r
  }\r
\r
  //\r
  // Install EFI Serial IO protocol on debug port\r
  //\r
  InstallSerialIo ();\r
\r
  Address = 0;\r
  Status = gBS->AllocatePages (\r
                  AllocateAnyPages,\r
                  EfiACPIMemoryNVS,\r
                  EFI_SIZE_TO_PAGES (sizeof(DEBUG_AGENT_MAILBOX) + PcdGet16(PcdDebugPortHandleBufferSize)),\r
                  &Address\r
                  );\r
  if (EFI_ERROR (Status)) {\r
    DEBUG ((DEBUG_ERROR, "DebugAgent: Cannot install configuration table for mailbox!\n"));\r
    CpuDeadLoop ();\r
  }\r
\r
  DebugTimerInterruptState = SaveAndSetDebugTimerInterrupt (FALSE);\r
\r
  NewMailbox = (DEBUG_AGENT_MAILBOX *) (UINTN) Address;\r
  //\r
  // Copy Mailbox and Debug Port Handle buffer to new location in ACPI NVS memory, because original Mailbox\r
  // and Debug Port Handle buffer may be free at runtime, SMM debug agent needs to access them\r
  //\r
  Mailbox = GetMailboxPointer ();\r
  CopyMem (NewMailbox, Mailbox, sizeof (DEBUG_AGENT_MAILBOX));\r
  CopyMem (NewMailbox + 1, (VOID *)(UINTN)Mailbox->DebugPortHandle, PcdGet16(PcdDebugPortHandleBufferSize));\r
  //\r
  // Update Debug Port Handle in new Mailbox\r
  //\r
  UpdateMailboxContent (NewMailbox, DEBUG_MAILBOX_DEBUG_PORT_HANDLE_INDEX, (UINT64)(UINTN)(NewMailbox + 1));\r
  mMailboxPointer = NewMailbox;\r
\r
  DebugTimerInterruptState = SaveAndSetDebugTimerInterrupt (DebugTimerInterruptState);\r
\r
  Status = gBS->InstallConfigurationTable (&gEfiDebugAgentGuid, (VOID *) mMailboxPointer);\r
  if (EFI_ERROR (Status)) {\r
    DEBUG ((DEBUG_ERROR, "DebugAgent: Failed to install configuration for mailbox!\n"));\r
    CpuDeadLoop ();\r
  }\r
}\r
\r
/**\r
  Debug Agent constructor function.\r
\r
  @param[in]  ImageHandle   The firmware allocated handle for the EFI image.\r
  @param[in]  SystemTable   A pointer to the EFI System Table.\r
\r
  @retval  RETURN_SUCCESS  When this function completed.\r
\r
**/\r
RETURN_STATUS\r
EFIAPI\r
DxeDebugAgentLibConstructor (\r
  IN EFI_HANDLE        ImageHandle,\r
  IN EFI_SYSTEM_TABLE  *SystemTable\r
  )\r
{\r
  if (mDxeCoreFlag) {\r
    //\r
    // Invoke internal constructor function only when DXE core links this library instance\r
    //\r
    InternalConstructorWorker ();\r
  }\r
\r
  return RETURN_SUCCESS;\r
}\r
\r
/**\r
  Get the pointer to Mailbox from the configuration table.\r
\r
  @return Pointer to Mailbox.\r
\r
**/\r
DEBUG_AGENT_MAILBOX *\r
GetMailboxFromConfigurationTable (\r
  VOID\r
  )\r
{\r
  EFI_STATUS               Status;\r
  DEBUG_AGENT_MAILBOX      *Mailbox;\r
\r
  Status = EfiGetSystemConfigurationTable (&gEfiDebugAgentGuid, (VOID **) &Mailbox);\r
  if (Status == EFI_SUCCESS && Mailbox != NULL) {\r
    VerifyMailboxChecksum (Mailbox);\r
    return Mailbox;\r
  } else {\r
    return NULL;\r
  }\r
}\r
\r
/**\r
  Get the pointer to Mailbox from the GUIDed HOB.\r
\r
  @param[in]  HobStart      The starting HOB pointer to search from.\r
\r
  @return Pointer to Mailbox.\r
\r
**/\r
DEBUG_AGENT_MAILBOX *\r
GetMailboxFromHob (\r
  IN VOID                  *HobStart\r
  )\r
{\r
  EFI_HOB_GUID_TYPE        *GuidHob;\r
  UINT64                   *MailboxLocation;\r
  DEBUG_AGENT_MAILBOX      *Mailbox;\r
\r
  GuidHob = GetNextGuidHob (&gEfiDebugAgentGuid, HobStart);\r
  if (GuidHob == NULL) {\r
    return NULL;\r
  }\r
  MailboxLocation = (UINT64 *) (GET_GUID_HOB_DATA(GuidHob));\r
  Mailbox = (DEBUG_AGENT_MAILBOX *)(UINTN)(*MailboxLocation);\r
  VerifyMailboxChecksum (Mailbox);\r
\r
  return Mailbox;\r
}\r
\r
/**\r
  Get Debug Agent Mailbox pointer.\r
\r
  @return Mailbox pointer.\r
\r
**/\r
DEBUG_AGENT_MAILBOX *\r
GetMailboxPointer (\r
  VOID\r
  )\r
{\r
  AcquireMpSpinLock (&mDebugMpContext.MailboxSpinLock);\r
  VerifyMailboxChecksum (mMailboxPointer);\r
  ReleaseMpSpinLock (&mDebugMpContext.MailboxSpinLock);\r
  return mMailboxPointer;\r
}\r
\r
/**\r
  Get debug port handle.\r
\r
  @return Debug port handle.\r
\r
**/\r
DEBUG_PORT_HANDLE\r
GetDebugPortHandle (\r
  VOID\r
  )\r
{\r
  return (DEBUG_PORT_HANDLE) (UINTN)(GetMailboxPointer ()->DebugPortHandle);\r
}\r
\r
/**\r
  Worker function to set up Debug Agent environment.\r
\r
  This function will set up IDT table and initialize the IDT entries and\r
  initialize CPU LOCAL APIC timer.\r
  It also tries to connect HOST if Debug Agent was not initialized before.\r
\r
  @param[in] Mailbox        Pointer to Mailbox.\r
\r
**/\r
VOID\r
SetupDebugAgentEnvironment (\r
  IN DEBUG_AGENT_MAILBOX       *Mailbox\r
  )\r
{\r
  IA32_DESCRIPTOR              Idtr;\r
  UINT16                       IdtEntryCount;\r
  UINT64                       DebugPortHandle;\r
  UINT32                       DebugTimerFrequency;\r
\r
  if (mMultiProcessorDebugSupport) {\r
    InitializeSpinLock (&mDebugMpContext.MpContextSpinLock);\r
    InitializeSpinLock (&mDebugMpContext.DebugPortSpinLock);\r
    InitializeSpinLock (&mDebugMpContext.MailboxSpinLock);\r
    //\r
    // Clear Break CPU index value\r
    //\r
    mDebugMpContext.BreakAtCpuIndex = (UINT32) -1;\r
  }\r
\r
  //\r
  // Get original IDT address and size.\r
  //\r
  AsmReadIdtr ((IA32_DESCRIPTOR *) &Idtr);\r
  IdtEntryCount = (UINT16) ((Idtr.Limit + 1) / sizeof (IA32_IDT_GATE_DESCRIPTOR));\r
  if (IdtEntryCount < 33) {\r
    ZeroMem (&mIdtEntryTable, sizeof (IA32_IDT_GATE_DESCRIPTOR) * 33);\r
    //\r
    // Copy original IDT table into new one\r
    //\r
    CopyMem (&mIdtEntryTable, (VOID *) Idtr.Base, Idtr.Limit + 1);\r
    //\r
    // Load new IDT table\r
    //\r
    Idtr.Limit = (UINT16) (sizeof (IA32_IDT_GATE_DESCRIPTOR) * 33 - 1);\r
    Idtr.Base  = (UINTN) &mIdtEntryTable;\r
    AsmWriteIdtr ((IA32_DESCRIPTOR *) &Idtr);\r
  }\r
\r
  //\r
  // Initialize the IDT table entries to support source level debug.\r
  //\r
  InitializeDebugIdt ();\r
\r
  //\r
  // If mMailboxPointer is not set before, set it\r
  //\r
  if (mMailboxPointer == NULL) {\r
    if (Mailbox != NULL) {\r
      //\r
      // If Mailbox exists, copy it into one global variable\r
      //\r
      CopyMem (&mMailbox, Mailbox, sizeof (DEBUG_AGENT_MAILBOX));\r
    } else {\r
      ZeroMem (&mMailbox, sizeof (DEBUG_AGENT_MAILBOX));\r
    }\r
    mMailboxPointer = &mMailbox;\r
  }\r
\r
  //\r
  // Initialize Debug Timer hardware and save its initial count and frequency\r
  //\r
  mDebugMpContext.DebugTimerInitCount = InitializeDebugTimer (&DebugTimerFrequency, TRUE);\r
  UpdateMailboxContent (mMailboxPointer, DEBUG_MAILBOX_DEBUG_TIMER_FREQUENCY, DebugTimerFrequency);\r
  //\r
  // Initialize debug communication port\r
  //\r
  DebugPortHandle = (UINT64) (UINTN)DebugPortInitialize ((VOID *)(UINTN)mMailboxPointer->DebugPortHandle, NULL);\r
  UpdateMailboxContent (mMailboxPointer, DEBUG_MAILBOX_DEBUG_PORT_HANDLE_INDEX, DebugPortHandle);\r
\r
  if (Mailbox == NULL) {\r
    //\r
    // Trigger one software interrupt to inform HOST\r
    //\r
    TriggerSoftInterrupt (SYSTEM_RESET_SIGNATURE);\r
    SetDebugFlag (DEBUG_AGENT_FLAG_MEMORY_READY, 1);\r
    //\r
    // Memory has been ready\r
    //\r
    if (IsHostAttached ()) {\r
      //\r
      // Trigger one software interrupt to inform HOST\r
      //\r
      TriggerSoftInterrupt (MEMORY_READY_SIGNATURE);\r
    }\r
  }\r
}\r
\r
\r
/**\r
  Initialize debug agent.\r
\r
  This function is used to set up debug environment for DXE phase.\r
\r
  If this function is called by DXE Core, Context must be the pointer\r
  to HOB list which will be used to get GUIDed HOB. It will enable\r
  interrupt to support break-in feature.\r
  If this function is called by DXE module, Context must be NULL. It\r
  will enable interrupt to support break-in feature.\r
\r
  @param[in] InitFlag     Init flag is used to decide initialize process.\r
  @param[in] Context      Context needed according to InitFlag.\r
  @param[in] Function     Continue function called by debug agent library; it was\r
                          optional.\r
\r
**/\r
VOID\r
EFIAPI\r
InitializeDebugAgent (\r
  IN UINT32                InitFlag,\r
  IN VOID                  *Context  OPTIONAL,\r
  IN DEBUG_AGENT_CONTINUE  Function  OPTIONAL\r
  )\r
{\r
  UINT64                       *MailboxLocation;\r
  DEBUG_AGENT_MAILBOX          *Mailbox;\r
  BOOLEAN                      InterruptStatus;\r
  VOID                         *HobList;\r
  IA32_DESCRIPTOR              IdtDescriptor;\r
  IA32_DESCRIPTOR              *Ia32Idtr;\r
  IA32_IDT_ENTRY               *Ia32IdtEntry;\r
  BOOLEAN                      PeriodicMode;\r
  UINTN                        TimerCycle;\r
\r
  if (InitFlag == DEBUG_AGENT_INIT_DXE_AP) {\r
    //\r
    // Check if CPU APIC Timer is working, otherwise initialize it.\r
    //\r
    InitializeLocalApicSoftwareEnable (TRUE);\r
    GetApicTimerState (NULL, &PeriodicMode, NULL);\r
    TimerCycle = GetApicTimerInitCount ();\r
    if (!PeriodicMode || TimerCycle == 0) {\r
      InitializeDebugTimer (NULL, FALSE);\r
    }\r
    //\r
    // Invoked by AP, enable interrupt to let AP could receive IPI from other processors\r
    //\r
    EnableInterrupts ();\r
    return ;\r
  }\r
\r
  //\r
  // Disable Debug Timer interrupt\r
  //\r
  SaveAndSetDebugTimerInterrupt (FALSE);\r
  //\r
  // Save and disable original interrupt status\r
  //\r
  InterruptStatus = SaveAndDisableInterrupts ();\r
\r
  //\r
  // Try to get mailbox firstly\r
  //\r
  HobList         = NULL;\r
  Mailbox         = NULL;\r
  MailboxLocation = NULL;\r
\r
  switch (InitFlag) {\r
\r
  case DEBUG_AGENT_INIT_DXE_LOAD:\r
    //\r
    // Check if Debug Agent has been initialized before\r
    //\r
    if (IsDebugAgentInitialzed ()) {\r
      DEBUG ((DEBUG_INFO, "Debug Agent: The former agent will be overwritten by the new one!\n"));\r
    }\r
\r
    mMultiProcessorDebugSupport = TRUE;\r
    //\r
    // Save original IDT table\r
    //\r
    AsmReadIdtr (&IdtDescriptor);\r
    mSaveIdtTableSize = IdtDescriptor.Limit + 1;\r
    mSavedIdtTable    = AllocateCopyPool (mSaveIdtTableSize, (VOID *) IdtDescriptor.Base);\r
    //\r
    // Check if Debug Agent initialized in DXE phase\r
    //\r
    Mailbox = GetMailboxFromConfigurationTable ();\r
    if (Mailbox == NULL) {\r
      //\r
      // Try to get mailbox from GUIDed HOB build in PEI\r
      //\r
      HobList = GetHobList ();\r
      Mailbox = GetMailboxFromHob (HobList);\r
    }\r
    //\r
    // Set up Debug Agent Environment and try to connect HOST if required\r
    //\r
    SetupDebugAgentEnvironment (Mailbox);\r
    //\r
    // For DEBUG_AGENT_INIT_S3, needn't to install configuration table and EFI Serial IO protocol\r
    // For DEBUG_AGENT_INIT_DXE_CORE, InternalConstructorWorker() will invoked in Constructor()\r
    //\r
    InternalConstructorWorker ();\r
    //\r
    // Enable Debug Timer interrupt\r
    //\r
    SaveAndSetDebugTimerInterrupt (TRUE);\r
    //\r
    // Enable interrupt to receive Debug Timer interrupt\r
    //\r
    EnableInterrupts ();\r
\r
    mDebugAgentInitialized = TRUE;\r
    FindAndReportModuleImageInfo (SIZE_4KB);\r
\r
    *(EFI_STATUS *)Context = EFI_SUCCESS;\r
\r
    break;\r
\r
  case DEBUG_AGENT_INIT_DXE_UNLOAD:\r
    if (mDebugAgentInitialized) {\r
      if (IsHostAttached ()) {\r
        *(EFI_STATUS *)Context = EFI_ACCESS_DENIED;\r
        //\r
        // Enable Debug Timer interrupt again\r
        //\r
        SaveAndSetDebugTimerInterrupt (TRUE);\r
      } else {\r
        //\r
        // Restore original IDT table\r
        //\r
        AsmReadIdtr (&IdtDescriptor);\r
        IdtDescriptor.Limit = (UINT16) (mSaveIdtTableSize - 1);\r
        CopyMem ((VOID *) IdtDescriptor.Base, mSavedIdtTable, mSaveIdtTableSize);\r
        AsmWriteIdtr (&IdtDescriptor);\r
        FreePool (mSavedIdtTable);\r
        mDebugAgentInitialized = FALSE;\r
        *(EFI_STATUS *)Context = EFI_SUCCESS;\r
      }\r
    } else {\r
      *(EFI_STATUS *)Context = EFI_NOT_STARTED;\r
    }\r
\r
    //\r
    // Restore interrupt state.\r
    //\r
    SetInterruptState (InterruptStatus);\r
    break;\r
\r
  case DEBUG_AGENT_INIT_DXE_CORE:\r
    mDxeCoreFlag                = TRUE;\r
    mMultiProcessorDebugSupport = TRUE;\r
    //\r
    // Try to get mailbox from GUIDed HOB build in PEI\r
    //\r
    HobList = Context;\r
    Mailbox = GetMailboxFromHob (HobList);\r
    //\r
    // Set up Debug Agent Environment and try to connect HOST if required\r
    //\r
    SetupDebugAgentEnvironment (Mailbox);\r
    //\r
    // Enable Debug Timer interrupt\r
    //\r
    SaveAndSetDebugTimerInterrupt (TRUE);\r
    //\r
    // Enable interrupt to receive Debug Timer interrupt\r
    //\r
    EnableInterrupts ();\r
\r
    break;\r
\r
  case DEBUG_AGENT_INIT_S3:\r
\r
    if (Context != NULL) {\r
      Ia32Idtr =  (IA32_DESCRIPTOR *) Context;\r
      Ia32IdtEntry = (IA32_IDT_ENTRY *)(Ia32Idtr->Base);\r
      MailboxLocation = (UINT64 *) ((UINTN) Ia32IdtEntry[DEBUG_MAILBOX_VECTOR].Bits.OffsetLow +\r
                                   ((UINTN) Ia32IdtEntry[DEBUG_MAILBOX_VECTOR].Bits.OffsetHigh << 16));\r
      Mailbox = (DEBUG_AGENT_MAILBOX *)(UINTN)(*MailboxLocation);\r
      VerifyMailboxChecksum (Mailbox);\r
    }\r
    //\r
    // Save Mailbox pointer in global variable\r
    //\r
    mMailboxPointer = Mailbox;\r
    //\r
    // Set up Debug Agent Environment and try to connect HOST if required\r
    //\r
    SetupDebugAgentEnvironment (Mailbox);\r
    //\r
    // Disable interrupt\r
    //\r
    DisableInterrupts ();\r
    FindAndReportModuleImageInfo (SIZE_4KB);\r
    if (GetDebugFlag (DEBUG_AGENT_FLAG_BREAK_BOOT_SCRIPT) == 1) {\r
      //\r
      // If Boot Script entry break is set, code will be break at here.\r
      //\r
      CpuBreakpoint ();\r
    }\r
    break;\r
\r
  default:\r
    //\r
    // Only DEBUG_AGENT_INIT_PREMEM_SEC and DEBUG_AGENT_INIT_POSTMEM_SEC are allowed for this\r
    // Debug Agent library instance.\r
    //\r
    DEBUG ((DEBUG_ERROR, "Debug Agent: The InitFlag value is not allowed!\n"));\r
    CpuDeadLoop ();\r
    break;\r
  }\r
}\r