Add doxygen style comments for functions in EBC module.

[mirror_edk2.git] / MdeModulePkg / Universal / EbcDxe / EbcExecute.h

diff --git a/MdeModulePkg/Universal/EbcDxe/EbcExecute.h b/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
index 91aada0d5551bc67cb73746154643363ad93b6a4..13eea0c9dc24876fc99504d6ba4b1bc3c3556d39 100644 (file)
--- a/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
+++ b/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
@@ -227,6 +227,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #define OPCODE_MOVIN  0x38\r
 #define OPCODE_MOVREL 0x39\r
 \r
+/**\r
+  Execute an EBC image from an entry point or from a published protocol.\r
+\r
+  @param  VmPtr             A pointer to a VM context.\r
+\r
+  @retval EFI_UNSUPPORTED   At least one of the opcodes is not supported.\r
+  @retval EFI_SUCCESS       All of the instructions are executed successfully.\r
+\r
+**/\r
 EFI_STATUS\r
 EbcExecute (\r
   IN VM_CONTEXT *VmPtr\r
@@ -235,12 +244,41 @@ EbcExecute (
 \r
 \r
 \r
+/**\r
+  Returns the version of the EBC virtual machine.\r
+    \r
+  @return The 64-bit version of EBC virtual machine.\r
+\r
+**/\r
 UINT64\r
 GetVmVersion (\r
   VOID\r
   )\r
 ;\r
 \r
+/**\r
+  Writes UINTN data to memory address.\r
+   \r
+  This routine is called by the EBC data\r
+  movement instructions that write to memory. Since these writes\r
+  may be to the stack, which looks like (high address on top) this,\r
+\r
+  [EBC entry point arguments]\r
+  [VM stack]\r
+  [EBC stack]\r
+\r
+  we need to detect all attempts to write to the EBC entry point argument\r
+  stack area and adjust the address (which will initially point into the \r
+  VM stack) to point into the EBC entry point arguments.\r
+\r
+  @param  VmPtr             A pointer to a VM context.\r
+  @param  Addr              Adddress to write to.\r
+  @param  Data              Value to write to Addr.\r
+\r
+  @retval EFI_SUCCESS       The instruction is executed successfully.  \r
+  @retval Other             Some error occurs when writing data to the address.\r
+\r
+**/\r
 EFI_STATUS\r
 VmWriteMemN (\r
   IN VM_CONTEXT   *VmPtr,\r
@@ -249,6 +287,29 @@ VmWriteMemN (
   )\r
 ;\r
 \r
+/**\r
+  Writes 64-bit data to memory address.\r
+   \r
+  This routine is called by the EBC data\r
+  movement instructions that write to memory. Since these writes\r
+  may be to the stack, which looks like (high address on top) this,\r
+\r
+  [EBC entry point arguments]\r
+  [VM stack]\r
+  [EBC stack]\r
+\r
+  we need to detect all attempts to write to the EBC entry point argument\r
+  stack area and adjust the address (which will initially point into the \r
+  VM stack) to point into the EBC entry point arguments.\r
+\r
+  @param  VmPtr             A pointer to a VM context.\r
+  @param  Addr              Adddress to write to.\r
+  @param  Data              Value to write to Addr.\r
+\r
+  @retval EFI_SUCCESS       The instruction is executed successfully.  \r
+  @retval Other             Some error occurs when writing data to the address.\r
+\r
+**/\r
 EFI_STATUS\r
 VmWriteMem64 (\r
   IN VM_CONTEXT *VmPtr,\r
@@ -305,6 +366,20 @@ struct _EFI_EBC_VM_TEST_PROTOCOL {
   EBC_VM_TEST_DASM    Disassemble;\r
 };\r
 \r
+/**\r
+  Given a pointer to a new VM context, execute one or more instructions. This\r
+  function is only used for test purposes via the EBC VM test protocol.\r
+\r
+  @param  This              A pointer to the EFI_EBC_VM_TEST_PROTOCOL structure.\r
+  @param  VmPtr             A pointer to a VM context.\r
+  @param  InstructionCount  A pointer to a UINTN value holding the number of\r
+                            instructions to execute. If it holds value of 0,\r
+                            then the instruction to be executed is 1.\r
+\r
+  @retval EFI_UNSUPPORTED   At least one of the opcodes is not supported.\r
+  @retval EFI_SUCCESS       All of the instructions are executed successfully.\r
+\r
+**/\r
 EFI_STATUS\r
 EbcExecuteInstructions (\r
   IN EFI_EBC_VM_TEST_PROTOCOL *This,\r