MdeModulePkg/EbcDxe: Add comments for functions

[mirror_edk2.git] / MdeModulePkg / Universal / EbcDxe / EbcDebugger / EdbDisasmSupport.h

diff --git a/MdeModulePkg/Universal/EbcDxe/EbcDebugger/EdbDisasmSupport.h b/MdeModulePkg/Universal/EbcDxe/EbcDebugger/EdbDisasmSupport.h
index 702673b8dff54261399a79bad03b3cc523bec3f1..801cbc123681f5f91d97a0eede3110a5250506fa 100644 (file)
--- a/MdeModulePkg/Universal/EbcDxe/EbcDebugger/EdbDisasmSupport.h
+++ b/MdeModulePkg/Universal/EbcDxe/EbcDebugger/EdbDisasmSupport.h
@@ -33,27 +33,69 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #define EDB_INSTRUCTION_CONTENT_MAX_LENGTH  30\r
 #define EDB_INSTRUCTION_CONTENT_MAX_SIZE    (EDB_INSTRUCTION_CONTENT_MAX_LENGTH * sizeof(CHAR16))\r
 \r
+/**\r
+\r
+  Set offset for Instruction name and content.\r
+\r
+  @param  InstructionNameOffset     - Instruction name offset\r
+  @param  InstructionContentOffset  - Instruction content offset\r
+\r
+**/\r
 VOID\r
 EdbSetOffset (\r
   IN UINTN InstructionNameOffset,\r
   IN UINTN InstructionContentOffset\r
   );\r
 \r
+/**\r
+\r
+  Pre instruction string construction.\r
+\r
+  @return Instruction string\r
+\r
+**/\r
 CHAR16 *\r
 EdbPreInstructionString (\r
   VOID\r
   );\r
 \r
+/**\r
+\r
+  Post instruction string construction.\r
+\r
+  @return Instruction string\r
+\r
+**/\r
 CHAR16 *\r
 EdbPostInstructionString (\r
   VOID\r
   );\r
 \r
+/**\r
+\r
+  Print the instruction name.\r
+\r
+  @param  Name - instruction name\r
+\r
+  @return Instruction name offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintInstructionName (\r
   IN CHAR16                 *Name\r
   );\r
 \r
+/**\r
+\r
+  Get Sign, NaturalUnits, and ConstantUnits of the WORD data.\r
+\r
+  @param  Data16        - WORD data\r
+  @param  NaturalUnits  - Natural Units of the WORD\r
+  @param  ConstantUnits - Constant Units of the WORD\r
+\r
+  @return Sign value of WORD\r
+\r
+**/\r
 BOOLEAN\r
 EdbGetNaturalIndex16 (\r
   IN  UINT16  Data16,\r
@@ -61,6 +103,17 @@ EdbGetNaturalIndex16 (
   OUT UINTN   *ConstantUnits\r
   );\r
 \r
+/**\r
+\r
+  Get Sign, NaturalUnits, and ConstantUnits of the DWORD data.\r
+\r
+  @param  Data32        - DWORD data\r
+  @param  NaturalUnits  - Natural Units of the DWORD\r
+  @param  ConstantUnits - Constant Units of the DWORD\r
+\r
+  @return Sign value of DWORD\r
+\r
+**/\r
 BOOLEAN\r
 EdbGetNaturalIndex32 (\r
   IN  UINT32  Data32,\r
@@ -68,6 +121,17 @@ EdbGetNaturalIndex32 (
   OUT UINTN   *ConstantUnits\r
   );\r
 \r
+/**\r
+\r
+  Get Sign, NaturalUnits, and ConstantUnits of the QWORD data.\r
+\r
+  @param  Data64        - QWORD data\r
+  @param  NaturalUnits  - Natural Units of the QWORD\r
+  @param  ConstantUnits - Constant Units of the QWORD\r
+\r
+  @return Sign value of QWORD\r
+\r
+**/\r
 BOOLEAN\r
 EdbGetNaturalIndex64 (\r
   IN  UINT64  Data64,\r
@@ -75,41 +139,115 @@ EdbGetNaturalIndex64 (
   OUT UINT64  *ConstantUnits\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical WORD raw index data to instruction content.\r
+\r
+  @param  Data16 - WORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintRawIndexData16 (\r
   IN UINT16                 Data16\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical DWORD raw index data to instruction content.\r
+\r
+  @param  Data32 - DWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintRawIndexData32 (\r
   IN UINT32                 Data32\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical QWORD raw index data to instruction content.\r
+\r
+  @param  Data64 - QWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintRawIndexData64 (\r
   IN UINT64                 Data64\r
   );\r
 \r
+/**\r
+\r
+  Print register 1 in operands.\r
+\r
+  @param  Operands - instruction operands\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintRegister1 (\r
   IN UINT8                  Operands\r
   );\r
 \r
+/**\r
+\r
+  Print register 2 in operands.\r
+\r
+  @param  Operands - instruction operands\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintRegister2 (\r
   IN UINT8                  Operands\r
   );\r
 \r
+/**\r
+\r
+  Print dedicated register 1 in operands.\r
+\r
+  @param Operands - instruction operands\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintDedicatedRegister1 (\r
   IN UINT8                  Operands\r
   );\r
 \r
+/**\r
+\r
+  Print dedicated register 2 in operands.\r
+\r
+  @param  Operands - instruction operands\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintDedicatedRegister2 (\r
   IN UINT8                  Operands\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical UINTN index data to instruction content.\r
+\r
+  @param  Sign          - Signed bit of UINTN data\r
+  @param  NaturalUnits  - natural units of UINTN data\r
+  @param  ConstantUnits - natural units of UINTN data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintIndexData (\r
   IN BOOLEAN                Sign,\r
@@ -117,6 +255,17 @@ EdbPrintIndexData (
   IN UINTN                  ConstantUnits\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical QWORD index data to instruction content.\r
+\r
+  @param  Sign          - Signed bit of QWORD data\r
+  @param  NaturalUnits  - natural units of QWORD data\r
+  @param  ConstantUnits - natural units of QWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintIndexData64 (\r
   IN BOOLEAN                Sign,\r
@@ -124,108 +273,297 @@ EdbPrintIndexData64 (
   IN UINT64                 ConstantUnits\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical BYTE immediate data to instruction content.\r
+\r
+  @param  Data - BYTE data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintImmData8 (\r
   IN UINT8                  Data\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical WORD immediate data to instruction content.\r
+\r
+  @param  Data - WORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintImmData16 (\r
   IN UINT16                 Data\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical DWORD immediate data to instruction content.\r
+\r
+  @param  Data - DWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintImmData32 (\r
   IN UINT32                 Data\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical QWORD immediate data to instruction content.\r
+\r
+  @param  Data - QWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintImmData64 (\r
   IN UINT64                 Data\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal UINTN immediate data to instruction content.\r
+\r
+  @param  Data - UINTN data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintImmDatan (\r
   IN UINTN                  Data\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal QWORD immediate data to instruction content.\r
+\r
+  @param  Data64 - QWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintImmData64n (\r
   IN UINT64                 Data64\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical BYTE to instruction content.\r
+\r
+  @param  Data8 - BYTE data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData8 (\r
   IN UINT8                  Data8\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical WORD to instruction content.\r
+\r
+  @param  Data16 - WORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData16 (\r
   IN UINT16                 Data16\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical DWORD to instruction content.\r
+\r
+  @param  Data32 - DWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData32 (\r
   IN UINT32                 Data32\r
   );\r
 \r
+/**\r
+\r
+  Print the hexical QWORD to instruction content.\r
+\r
+  @param  Data64 - QWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData64 (\r
   IN UINT64                 Data64\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal unsigned UINTN to instruction content.\r
+\r
+  @param  Data - unsigned UINTN data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintDatan (\r
   IN UINTN                  Data\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal unsigned QWORD to instruction content.\r
+\r
+  @param  Data64 - unsigned QWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData64n (\r
   IN UINT64                 Data64\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal signed BYTE to instruction content.\r
+\r
+  @param  Data8 - signed BYTE data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData8s (\r
   IN UINT8                  Data8\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal signed WORD to instruction content.\r
+\r
+  @param  Data16 - signed WORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData16s (\r
   IN UINT16                 Data16\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal signed DWORD to instruction content.\r
+\r
+  @param  Data32 - signed DWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData32s (\r
   IN UINT32                 Data32\r
   );\r
 \r
+/**\r
+\r
+  Print the decimal signed QWORD to instruction content.\r
+\r
+  @param  Data64 - signed QWORD data\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintData64s (\r
   IN UINT64                 Data64\r
   );\r
 \r
+/**\r
+\r
+  Print the comma to instruction content.\r
+\r
+  @return Instruction content offset\r
+\r
+**/\r
 UINTN\r
 EdbPrintComma (\r
   VOID\r
   );\r
 \r
+/**\r
+\r
+  Find the symbol string according to address, then print it.\r
+\r
+  @param  Address - instruction address\r
+\r
+  @retval 1 - symbol string is found and printed\r
+  @retval 0 - symbol string not found\r
+\r
+**/\r
 UINTN\r
 EdbFindAndPrintSymbol (\r
   IN UINTN                  Address\r
   );\r
 \r
+/**\r
+\r
+  Print the EBC byte code.\r
+\r
+  @param  InstructionAddress - instruction address\r
+  @param  InstructionNumber  - instruction number\r
+\r
+**/\r
 VOID\r
 EdbPrintRaw (\r
   IN EFI_PHYSICAL_ADDRESS   InstructionAddress,\r
   IN UINTN                  InstructionNumber\r
   );\r
 \r
+/**\r
+\r
+  Print the EBC asm code.\r
+\r
+  @param  DebuggerPrivate - EBC Debugger private data structure\r
+  @param  SystemContext   - EBC system context.\r
+\r
+  @retval EFI_SUCCESS - show disasm successfully\r
+\r
+**/\r
 EFI_STATUS\r
 EdbShowDisasm (\r
   IN     EFI_DEBUGGER_PRIVATE_DATA *DebuggerPrivate,\r
   IN     EFI_SYSTEM_CONTEXT        SystemContext\r
   );\r
 \r
+/**\r
+\r
+  Get register value accroding to the system context, and register index.\r
+\r
+  @param  SystemContext   - EBC system context.\r
+  @param  Index           - EBC register index\r
+\r
+  @return register value\r
+\r
+**/\r
 UINT64\r
 GetRegisterValue (\r
   IN     EFI_SYSTEM_CONTEXT        SystemContext,\r