Add doxygen style comments for functions in EBC module.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5194 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 150 insertions, 21 deletions

diff --git a/MdeModulePkg/Universal/EbcDxe/EbcInt.h b/MdeModulePkg/Universal/EbcDxe/EbcInt.h
index c9f2b825f1..720ee2668a 100644
--- a/MdeModulePkg/Universal/EbcDxe/EbcInt.h
+++ b/MdeModulePkg/Universal/EbcDxe/EbcInt.h
@@ -79,6 +79,23 @@ extern VM_CONTEXT                    *mVmPtr;
 //

 #define VM_STACK_KEY_VALUE  0xDEADBEEF

 

+/**

+  Create thunks for an EBC image entry point, or an EBC protocol service.

+

+  @param  ImageHandle           Image handle for the EBC image. If not null, then

+                                we're creating a thunk for an image entry point.

+  @param  EbcEntryPoint         Address of the EBC code that the thunk is to call

+  @param  Thunk                 Returned thunk we create here

+  @param  Flags                 Flags indicating options for creating the thunk

+

+  @retval EFI_SUCCESS           The thunk was created successfully.

+  @retval EFI_INVALID_PARAMETER The parameter of EbcEntryPoint is not 16-bit

+                                aligned.

+  @retval EFI_OUT_OF_RESOURCES  There is not enough memory to created the EBC

+                                Thunk.

+  @retval EFI_BUFFER_TOO_SMALL  EBC_THUNK_SIZE is not larger enough.

+

+**/

 EFI_STATUS

 EbcCreateThunks (

   IN EFI_HANDLE           ImageHandle,

@@ -88,6 +105,19 @@ EbcCreateThunks (
   )

 ;

 

+/**

+  Add a thunk to our list of thunks for a given image handle.

+  Also flush the instruction cache since we've written thunk code

+  to memory that will be executed eventually.

+

+  @param  ImageHandle            The image handle to which the thunk is tied.

+  @param  ThunkBuffer            The buffer that has been created/allocated.

+  @param  ThunkSize              The size of the thunk memory allocated.

+

+  @retval EFI_OUT_OF_RESOURCES   Memory allocation failed.

+  @retval EFI_SUCCESS            The function completed successfully.

+

+**/

 EFI_STATUS

 EbcAddImageThunk (

   IN EFI_HANDLE     ImageHandle,

@@ -100,6 +130,17 @@ EbcAddImageThunk (
 // The interpreter calls these when an exception is detected,

 // or as a periodic callback.

 //

+/**

+  The VM interpreter calls this function when an exception is detected.

+

+  @param  ExceptionType          Specifies the processor exception detected.

+  @param  ExceptionFlags         Specifies the exception context. 

+  @param  VmPtr                  Pointer to a VM context for passing info to the

+                                 EFI debugger.

+

+  @retval EFI_SUCCESS            This function completed successfully.

+

+**/

 EFI_STATUS

 EbcDebugSignalException (

   IN EFI_EXCEPTION_TYPE ExceptionType,

@@ -117,28 +158,56 @@ EbcDebugSignalException (
 #define STACK_POOL_SIZE               (1024 * 1020)

 #define MAX_STACK_NUM                 4

 

-EFI_STATUS

-EbcDebugSignalPeriodic (

-  IN VM_CONTEXT   *VmPtr

-  )

-;

-

 //

 // External low level functions that are native-processor dependent

-//

+// 

+/** 

+  The VM thunk code stuffs an EBC entry point into a processor 

+  register. Since we can't use inline assembly to get it from

+  the interpreter C code, stuff it into the return value

+  register and return.

+ 

+  @return  The contents of the register in which the entry point is passed.

+ 

+**/ 

 UINTN

+EFIAPI

 EbcLLGetEbcEntryPoint (

   VOID

   )

 ;

 

+/**

+  Returns the caller's value of the stack pointer.

+

+  We adjust it by 4 here because when they called us, the return address

+  is put on the stack, thereby lowering it by 4 bytes.

+

+  @return The current value of the stack pointer for the caller. 

+

+**/

 UINTN

+EFIAPI

 EbcLLGetStackPointer (

   VOID

   )

 ;

 

+/**

+  This function is called to execute an EBC CALLEX instruction.

+  This instruction requires that we thunk out to external native

+  code. For x64, we switch stacks, copy the arguments to the stack 

+  and jump to the specified function.

+  On return, we restore the stack pointer to its original location.

+  Destroys no working registers.

+

+  @param  CallAddr     The function address.

+  @param  EbcSp        The new EBC stack pointer.

+  @param  FramePtr     The frame pointer.

+   

+**/

 VOID

+EFIAPI

 EbcLLCALLEXNative (

   IN UINTN        CallAddr,

   IN UINTN        EbcSp,

@@ -146,47 +215,114 @@ EbcLLCALLEXNative (
   )

 ;

 

+/**

+  This function is called to execute an EBC CALLEX instruction.

+  The function check the callee's content to see whether it is common native

+  code or a thunk to another piece of EBC code.

+  If the callee is common native code, use EbcLLCAllEXASM to manipulate,

+  otherwise, set the VM->IP to target EBC code directly to avoid another VM

+  be startup which cost time and stack space.

+

+  @param  VmPtr            Pointer to a VM context.

+  @param  FuncAddr         Callee's address

+  @param  NewStackPointer  New stack pointer after the call

+  @param  FramePtr         New frame pointer after the call

+  @param  Size             The size of call instruction

+

+**/

 VOID

 EbcLLCALLEX (

   IN VM_CONTEXT   *VmPtr,

-  IN UINTN        CallAddr,

-  IN UINTN        EbcSp,

+  IN UINTN        FuncAddr,

+  IN UINTN        NewStackPointer,

   IN VOID         *FramePtr,

   IN UINT8        Size

   )

 ;

 

+/**

+  When EBC calls native, on return the VM has to stuff the return

+  value into a VM register. It's assumed here that the value is still

+  in the register, so simply return and the caller should get the

+  return result properly.

+

+  @return The unmodified value returned by the native code. 

+

+**/

 INT64

+EFIAPI

 EbcLLGetReturnValue (

   VOID

   )

 ;

 

+/**

+  Returns the stack index and buffer assosicated with the Handle parameter.

+

+  @param  Handle                The EFI handle as the index to the EBC stack. 

+  @param  StackBuffer           A pointer to hold the returned stack buffer.

+  @param  BufferIndex           A pointer to hold the returned stack index.

+   

+  @retval EFI_OUT_OF_RESOURCES  The Handle parameter does not correspond to any

+                                existing EBC stack.

+  @retval EFI_SUCCESS           The stack index and buffer were found and

+                                returned to the caller.

+

+**/

 EFI_STATUS

 GetEBCStack(

-  EFI_HANDLE Handle,

-  VOID       **StackBuffer,

-  UINTN      *BufferIndex

+  IN  EFI_HANDLE Handle,

+  OUT VOID       **StackBuffer,

+  OUT UINTN      *BufferIndex

   );

 

+/**

+  Returns from the EBC stack by stack Index. 

+   

+  @param  Index        Specifies which EBC stack to return from.

+   

+  @retval EFI_SUCCESS  The function completed successfully.

+

+**/

 EFI_STATUS

 ReturnEBCStack(

-  UINTN Index

+  IN UINTN Index

   );

 

+/**

+  Allocates memory to hold all the EBC stacks.

+

+  @retval EFI_SUCCESS          The EBC stacks were allocated successfully. 

+  @retval EFI_OUT_OF_RESOURCES Not enough memory available for EBC stacks.

+

+**/

 EFI_STATUS

 InitEBCStack (

   VOID

   );

 

+/**

+  Free all EBC stacks allocated before.

+

+  @retval EFI_SUCCESS   All the EBC stacks were freed.

+

+**/

 EFI_STATUS

 FreeEBCStack(

   VOID

   );

 

+/**

+  Returns from the EBC stack associated with the Handle parameter. 

+   

+  @param  Handle      Specifies the EFI handle to find the EBC stack with.

+   

+  @retval EFI_SUCCESS The function completed successfully.

+

+**/

 EFI_STATUS

 ReturnEBCStackByHandle(

-  EFI_HANDLE Handle

+  IN EFI_HANDLE Handle

   );

 //

 // Defines for a simple EBC debugger interface

@@ -255,13 +391,6 @@ typedef struct {
 

 #define EBC_PROTOCOL_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32 ('e', 'b', 'c', 'p')

 

-struct _EBC_PROTOCOL_PRIVATE_DATA {

-  UINT32            Signature;

-  EFI_EBC_PROTOCOL  EbcProtocol;

-  UINTN             StackBase;

-  UINTN             StackTop;

-  UINTN             StackSize;

-} ;

 

 #define EBC_PROTOCOL_PRIVATE_DATA_FROM_THIS(a) \

       CR(a, EBC_PROTOCOL_PRIVATE_DATA, EbcProtocol, EBC_PROTOCOL_PRIVATE_DATA_SIGNATURE)