sync comments, fix function header, rename variable name to follow coding style.

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

diff --git a/MdeModulePkg/Universal/EbcDxe/EbcExecute.h b/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
index 91aada0d5551bc67cb73746154643363ad93b6a4..88bf9d5843a81575375cb31e5db519eacdba9594 100644 (file)
--- a/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
+++ b/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
@@ -3,7 +3,7 @@
   be of use to a disassembler for the most part. Also provides function\r
   prototypes for VM functions.\r
 \r
-Copyright (c) 2006, Intel Corporation\r
+Copyright (c) 2006 - 2008, Intel Corporation. <BR>\r
 All rights reserved. This program and the accompanying materials\r
 are licensed and made available under the terms and conditions of the BSD License\r
 which accompanies this distribution.  The full text of the license may be found at\r
@@ -227,35 +227,92 @@ 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
-  )\r
-;\r
+  );\r
+\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
+/**\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
   IN UINTN        Addr,\r
   IN UINTN        Data\r
-  )\r
-;\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
-  UINTN         Addr,\r
-  IN UINT64     Data\r
-  )\r
-;\r
+  IN VM_CONTEXT   *VmPtr,\r
+  IN UINTN        Addr,\r
+  IN UINT64       Data\r
+  );\r
 \r
 //\r
 // Define a protocol for an EBC VM test interface.\r
@@ -305,12 +362,25 @@ 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
   IN VM_CONTEXT               *VmPtr,\r
   IN OUT UINTN                *InstructionCount\r
-  )\r
-;\r
+  );\r
 \r
 #endif // ifndef _EBC_EXECUTE_H_\r