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 b1926ee975c85cec099c3b49371fee552cf501cf..88bf9d5843a81575375cb31e5db519eacdba9594 100644 (file)
--- a/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
+++ b/MdeModulePkg/Universal/EbcDxe/EbcExecute.h
@@ -1,25 +1,18 @@
-/*++\r
-\r
-Copyright (c) 2006, Intel Corporation                                                         \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
-http://opensource.org/licenses/bsd-license.php                                            \r
-                                                                                          \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
-\r
-Module Name:\r
-\r
-  EbcExecute.h\r
-\r
-Abstract:\r
-\r
+/** @file\r
   Header file for Virtual Machine support. Contains EBC defines that can\r
-  be of use to a disassembler for the most part. Also provides function \r
+  be of use to a disassembler for the most part. Also provides function\r
   prototypes for VM functions.\r
 \r
---*/\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
+http://opensource.org/licenses/bsd-license.php\r
+\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
 \r
 #ifndef _EBC_EXECUTE_H_\r
 #define _EBC_EXECUTE_H_\r
@@ -234,35 +227,92 @@ Abstract:
 #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
@@ -312,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