Synchronized with UEFI Spec

[mirror_edk2.git] / MdePkg / Include / Protocol / DebugSupport.h

diff --git a/MdePkg/Include/Protocol/DebugSupport.h b/MdePkg/Include/Protocol/DebugSupport.h
index 450d6f04ae30e583aeae4bb18befb2c3f132272e..0eb4eee7b34c145a0b8cbf38b08576231354fbc8 100644 (file)
--- a/MdePkg/Include/Protocol/DebugSupport.h
+++ b/MdePkg/Include/Protocol/DebugSupport.h
@@ -33,13 +33,14 @@ typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL;
   }\r
 \r
 ///\r
-/// Debug Support definitions\r
+/// Processor exception to be hooked.\r
+/// All exception types for IA32, X64, Itanium and EBC processors are defined.\r
 ///\r
 typedef INTN  EFI_EXCEPTION_TYPE;\r
 \r
-//\r
-//  IA-32 processor exception types\r
-//\r
+///\r
+///  IA-32 processor exception types\r
+///\r
 #define EXCEPT_IA32_DIVIDE_ERROR    0\r
 #define EXCEPT_IA32_DEBUG           1\r
 #define EXCEPT_IA32_NMI             2\r
@@ -58,9 +59,6 @@ typedef INTN  EFI_EXCEPTION_TYPE;
 #define EXCEPT_IA32_MACHINE_CHECK   18\r
 #define EXCEPT_IA32_SIMD            19\r
 \r
-///\r
-///  IA-32 processor context definition\r
-///\r
 ///\r
 /// FXSAVE_STATE\r
 /// FP / MMX / XMM registers (see fxrstor instruction definition)\r
@@ -95,6 +93,9 @@ typedef struct {
   UINT8   Reserved11[14 * 16];\r
 } EFI_FX_SAVE_STATE_IA32;\r
 \r
+///\r
+///  IA-32 processor context definition\r
+///\r
 typedef struct {\r
   UINT32                 ExceptionData;\r
   EFI_FX_SAVE_STATE_IA32 FxSaveState;\r
@@ -131,9 +132,9 @@ typedef struct {
   UINT32                 Eax;\r
 } EFI_SYSTEM_CONTEXT_IA32;\r
 \r
-//\r
-//  X64 processor exception types\r
-//\r
+///\r
+///  x64 processor exception types\r
+///\r
 #define EXCEPT_X64_DIVIDE_ERROR    0\r
 #define EXCEPT_X64_DEBUG           1\r
 #define EXCEPT_X64_NMI             2\r
@@ -152,8 +153,6 @@ typedef struct {
 #define EXCEPT_X64_MACHINE_CHECK   18\r
 #define EXCEPT_X64_SIMD            19\r
 \r
-///\r
-///  X64 processor context definition\r
 ///\r
 /// FXSAVE_STATE\r
 /// FP / MMX / XMM registers (see fxrstor instruction definition)\r
@@ -188,6 +187,9 @@ typedef struct {
   UINT8   Reserved11[14 * 16];\r
 } EFI_FX_SAVE_STATE_X64;\r
 \r
+///\r
+///  x64 processor context definition\r
+///\r
 typedef struct {\r
   UINT64                ExceptionData;\r
   EFI_FX_SAVE_STATE_X64 FxSaveState;\r
@@ -233,9 +235,9 @@ typedef struct {
   UINT64                R15;\r
 } EFI_SYSTEM_CONTEXT_X64;\r
 \r
-//\r
-//  IPF processor exception types\r
-//\r
+///\r
+///  Itanium Processor Family Exception types\r
+///\r
 #define EXCEPT_IPF_VHTP_TRANSLATION       0\r
 #define EXCEPT_IPF_INSTRUCTION_TLB        1\r
 #define EXCEPT_IPF_DATA_TLB               2\r
@@ -434,20 +436,20 @@ typedef struct {
 \r
 } EFI_SYSTEM_CONTEXT_IPF;\r
 \r
-//\r
-//  EBC processor exception types\r
-//\r
+///\r
+///  EBC processor exception types\r
+///\r
 #define EXCEPT_EBC_UNDEFINED            0\r
 #define EXCEPT_EBC_DIVIDE_ERROR         1\r
 #define EXCEPT_EBC_DEBUG                2\r
 #define EXCEPT_EBC_BREAKPOINT           3\r
 #define EXCEPT_EBC_OVERFLOW             4\r
-#define EXCEPT_EBC_INVALID_OPCODE       5   // opcode out of range\r
+#define EXCEPT_EBC_INVALID_OPCODE       5   ///< opcode out of range\r
 #define EXCEPT_EBC_STACK_FAULT          6\r
 #define EXCEPT_EBC_ALIGNMENT_CHECK      7\r
-#define EXCEPT_EBC_INSTRUCTION_ENCODING 8   // malformed instruction\r
-#define EXCEPT_EBC_BAD_BREAK            9   // BREAK 0 or undefined BREAK\r
-#define EXCEPT_EBC_STEP                 10  // to support debug stepping\r
+#define EXCEPT_EBC_INSTRUCTION_ENCODING 8   ///< malformed instruction\r
+#define EXCEPT_EBC_BAD_BREAK            9   ///< BREAK 0 or undefined BREAK\r
+#define EXCEPT_EBC_STEP                 10  ///< to support debug stepping\r
 ///\r
 /// For coding convenience, define the maximum valid EBC exception.\r
 ///\r
@@ -487,7 +489,7 @@ typedef union {
 /**                                                                 \r
   Registers and enables an exception callback function for the specified exception.\r
     \r
-  @param  ExceptionType         Exception types in EBC, IA-32, X64, or IPF\r
+  @param  ExceptionType         Exception types in EBC, IA-32, x64, or IPF\r
   @param  SystemContext         Exception content.\r
                                    \r
 **/\r
@@ -571,7 +573,7 @@ EFI_STATUS
     \r
   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.\r
   @param  ProcessorIndex        Specifies which processor the callback function applies to.\r
-  @param  PeriodicCallback      A pointer to a function of type EXCEPTION_CALLBACK that is called\r
+  @param  ExceptionCallback     A pointer to a function of type EXCEPTION_CALLBACK that is called\r
                                 when the processor exception specified by ExceptionType occurs.  \r
   @param  ExceptionType         Specifies which processor exception to hook.                       \r
                                 \r
@@ -613,16 +615,15 @@ EFI_STATUS
   IN UINT64                              Length\r
   );\r
 \r
-//\r
-// DebugSupport protocol definition\r
-//\r
-/**\r
-  @par Protocol Description:\r
-  This protocol provides the services to allow the debug agent to register \r
-  callback functions that are called either periodically or when specific \r
-  processor exceptions occur.\r
-**/\r
+///\r
+/// This protocol provides the services to allow the debug agent to register \r
+/// callback functions that are called either periodically or when specific \r
+/// processor exceptions occur.\r
+///\r
 struct _EFI_DEBUG_SUPPORT_PROTOCOL {\r
+  ///\r
+  /// Declares the processor architecture for this instance of the EFI Debug Support protocol.\r
+  ///\r
   EFI_INSTRUCTION_SET_ARCHITECTURE  Isa;\r
   EFI_GET_MAXIMUM_PROCESSOR_INDEX   GetMaximumProcessorIndex;\r
   EFI_REGISTER_PERIODIC_CALLBACK    RegisterPeriodicCallback;\r