Synchronize function's comments with UEFI specification.

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

5 files changed, 107 insertions, 34 deletions

diff --git a/MdePkg/Include/Protocol/Tcp4.h b/MdePkg/Include/Protocol/Tcp4.h
index fe37899f74..9fb8f5d1e3 100644
--- a/MdePkg/Include/Protocol/Tcp4.h
+++ b/MdePkg/Include/Protocol/Tcp4.h
@@ -33,7 +33,7 @@
 typedef struct _EFI_TCP4_PROTOCOL EFI_TCP4_PROTOCOL;

 

 typedef struct {

-  EFI_HANDLE        InstanceHandle;

+  EFI_HANDLE              InstanceHandle;

   EFI_IPv4_ADDRESS        LocalAddress;

   UINT16                  LocalPort;

   EFI_IPv4_ADDRESS        RemoteAddress;

diff --git a/MdePkg/Include/Protocol/Timer.h b/MdePkg/Include/Protocol/Timer.h
index cdf7b9bda9..55ea880534 100644
--- a/MdePkg/Include/Protocol/Timer.h
+++ b/MdePkg/Include/Protocol/Timer.h
@@ -31,7 +31,7 @@ typedef struct _EFI_TIMER_ARCH_PROTOCOL   EFI_TIMER_ARCH_PROTOCOL;
 /**

   This function of this type is called when a timer interrupt fires.  This 

   function executes at TPL_HIGH_LEVEL.  The DXE Core will register a funtion

-  of tyis type to be called for the timer interrupt, so it can know how much 

+  of this type to be called for the timer interrupt, so it can know how much 

   time has passed.  This information is used to signal timer based events.  

 

   @param  Time   Time since the last timer interrupt in 100 ns units. This will

diff --git a/MdePkg/Include/Protocol/UsbIo.h b/MdePkg/Include/Protocol/UsbIo.h
index 8f24f1a98c..fde139eb6e 100644
--- a/MdePkg/Include/Protocol/UsbIo.h
+++ b/MdePkg/Include/Protocol/UsbIo.h
@@ -134,13 +134,23 @@ EFI_STATUS
   typically used to transfer large amounts of data to/from USB devices.

 

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.

-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB

-                                device.

+  @param  DeviceEndpoint        The destination USB device endpoint to which the 

+                                device request is being sent. DeviceEndpoint must 

+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, 

+                                otherwise EFI_INVALID_PARAMETER is returned. If 

+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 

+                                is returned. The MSB of this parameter indicates 

+                                the endpoint direction. The number “1” stands for 

+                                an IN endpoint, and “0” stands for an OUT endpoint.

   @param  Data                  A pointer to the buffer of data that will be transmitted to USB

                                 device or received from USB device.

   @param  DataLength            The size, in bytes, of the data buffer specified by Data.

+                                On input, the size, in bytes, of the data buffer specified by Data.

+                                On output, the number of bytes that were actually transferred.

   @param  Timeout               Indicating the transfer should be completed within this time frame.

-                                The units are in milliseconds.

+                                The units are in milliseconds. If Timeout is 0, then the 

+                                caller must wait for the function to be completed until 

+                                EFI_SUCCESS or EFI_DEVICE_ERROR is returned.

   @param  Status                This parameter indicates the USB transfer status.

 

   @retval EFI_SUCCESS           The bulk transfer has been successfully executed.

@@ -168,18 +178,28 @@ EFI_STATUS
   a fixed rate.

 

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.

-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB

-                                device.

+  @param  DeviceEndpoint        The destination USB device endpoint to which the 

+                                device request is being sent. DeviceEndpoint must 

+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, 

+                                otherwise EFI_INVALID_PARAMETER is returned. If 

+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 

+                                is returned. The MSB of this parameter indicates 

+                                the endpoint direction. The number “1” stands for 

+                                an IN endpoint, and “0” stands for an OUT endpoint.

   @param  IsNewTransfer         If TRUE, a new transfer will be submitted to USB controller. If

                                 FALSE, the interrupt transfer is deleted from the device's interrupt

                                 transfer queue.

   @param  PollingInterval       Indicates the periodic rate, in milliseconds, that the transfer is to be

-                                executed.

+                                executed.This parameter is required when IsNewTransfer is TRUE. The 

+                                value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. 

+                                The units are in milliseconds.

   @param  DataLength            Specifies the length, in bytes, of the data to be received from the

-                                USB device.

+                                USB device. This parameter is only required when IsNewTransfer is TRUE.

   @param  InterruptCallback     The Callback function. This function is called if the asynchronous

-                                interrupt transfer is completed.

-  @param  Context               Data passed to the InterruptCallback function.

+                                interrupt transfer is completed. This parameter is required 

+                                when IsNewTransfer is TRUE.

+  @param  Context               Data passed to the InterruptCallback function. This is an optional 

+                                parameter and may be NULL.

 

   @retval EFI_SUCCESS           The asynchronous USB transfer request transfer has been successfully executed.

   @retval EFI_DEVICE_ERROR      The asynchronous USB transfer request failed.

@@ -201,13 +221,22 @@ EFI_STATUS
   This function is used to manage a USB device with an interrupt transfer pipe.

 

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.

-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB

-                                device.

+  @param  DeviceEndpoint        The destination USB device endpoint to which the 

+                                device request is being sent. DeviceEndpoint must 

+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, 

+                                otherwise EFI_INVALID_PARAMETER is returned. If 

+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 

+                                is returned. The MSB of this parameter indicates 

+                                the endpoint direction. The number “1” stands for 

+                                an IN endpoint, and “0” stands for an OUT endpoint.

   @param  Data                  A pointer to the buffer of data that will be transmitted to USB

                                 device or received from USB device.

   @param  DataLength            On input, then size, in bytes, of the buffer Data. On output, the

                                 amount of data actually transferred.

-  @param  Timeout               The time out, in seconds, for this transfer.

+  @param  Timeout               The time out, in seconds, for this transfer. If Timeout is 0, 

+                                then the caller must wait for the function to be completed 

+                                until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the 

+                                transfer is not completed in this time frame, then EFI_TIMEOUT is returned.

   @param  Status                This parameter indicates the USB transfer status.

 

   @retval EFI_SUCCESS           The sync interrupt transfer has been successfully executed.

@@ -232,8 +261,14 @@ EFI_STATUS
   transfer is typically used to transfer streaming data.

 

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.

-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB

-                                device.

+  @param  DeviceEndpoint        The destination USB device endpoint to which the 

+                                device request is being sent. DeviceEndpoint must 

+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, 

+                                otherwise EFI_INVALID_PARAMETER is returned. If 

+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 

+                                is returned. The MSB of this parameter indicates 

+                                the endpoint direction. The number “1” stands for 

+                                an IN endpoint, and “0” stands for an OUT endpoint.

   @param  Data                  A pointer to the buffer of data that will be transmitted to USB

                                 device or received from USB device.

   @param  DataLength            The size, in bytes, of the data buffer specified by Data.

@@ -261,12 +296,20 @@ EFI_STATUS
   transfer is typically used to transfer streaming data.

 

   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.

-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB

-                                device.

+  @param  DeviceEndpoint        The destination USB device endpoint to which the 

+                                device request is being sent. DeviceEndpoint must 

+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, 

+                                otherwise EFI_INVALID_PARAMETER is returned. If 

+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 

+                                is returned. The MSB of this parameter indicates 

+                                the endpoint direction. The number “1” stands for 

+                                an IN endpoint, and “0” stands for an OUT endpoint.

   @param  Data                  A pointer to the buffer of data that will be transmitted to USB

                                 device or received from USB device.

   @param  DataLength            The size, in bytes, of the data buffer specified by Data.

-  @param  IsochronousCallback   The IsochronousCallback() function.

+                                This is an optional parameter and may be NULL.

+  @param  IsochronousCallback   The IsochronousCallback() function.This function is 

+                                called if the requested isochronous transfer is completed.

   @param  Context               Data passed to the IsochronousCallback() function.

 

   @retval EFI_SUCCESS           The asynchronous isochronous transfer has been successfully submitted

@@ -389,7 +432,10 @@ EFI_STATUS
   @param  LangID                  The Language ID for the string being retrieved.

   @param  StringID                The ID of the string being retrieved.

   @param  String                  A pointer to a buffer allocated by this function with

-                                  AllocatePool() to store the string.

+                                  AllocatePool() to store the string.If this function 

+                                  returns EFI_SUCCESS, it stores the string the caller 

+                                  wants to get. The caller should release the string 

+                                  buffer with FreePool() after the string is not used any more.

 

   @retval EFI_SUCCESS             The string was retrieved successfully.

   @retval EFI_NOT_FOUND           The string specified by LangID and StringID was not found.

@@ -410,6 +456,10 @@ EFI_STATUS
 

   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.

   @param  LangIDTable             Language ID for the string the caller wants to get.

+                                  This is a 16-bit ID defined by Microsoft. This 

+                                  buffer pointer is allocated and maintained by 

+                                  the USB Bus Driver, the caller should not modify 

+                                  its contents.

   @param  TableSize               The size, in bytes, of the table LangIDTable.

 

   @retval EFI_SUCCESS             The support languages were retrieved successfully.

diff --git a/MdePkg/Include/Protocol/Variable.h b/MdePkg/Include/Protocol/Variable.h
index 9c09f1b498..82c3bfc225 100644
--- a/MdePkg/Include/Protocol/Variable.h
+++ b/MdePkg/Include/Protocol/Variable.h
@@ -1,13 +1,24 @@
 /** @file

   Variable Architectural Protocol as defined in PI Specification VOLUME 2 DXE

 

-  This code is used to produce the UEFI 2.0 runtime variable services

-

-  The GetVariable (), GetNextVariableName (), and SetVariable () UEFI 2.0 

-  services are added to the EFI system table and the 

-  EFI_VARIABLE_ARCH_PROTOCOL_GUID protocol is registered with a NULL pointer.

-

-  No CRC of the EFI system table is required, as it is done in the DXE core.

+  This provides the services required to get and set environment variables. This 

+  protocol must be produced by a runtime DXE driver and may be consumed only by 

+  the DXE Foundation. The DXE driver that produces this protocol must be a runtime 

+  driver. This driver is responsible for initializing the GetVariable(), 

+  GetNextVariableName(), and SetVariable() fields of the UEFI Runtime Services Table.

+

+  After the three fields of the UEFI Runtime Services Table have been initialized, 

+  the driver must install the EFI_VARIABLE_ARCH_PROTOCOL_GUID on a new handle with 

+  a NULL interface pointer. The installation of this protocol informs the DXE Foundation 

+  that the read-only and the volatile environment variable related services are 

+  now available and that the DXE Foundation must update the 32-bit CRC of the UEFI 

+  Runtime Services Table. The full complement of environment variable services are 

+  not available until both this protocol and EFI_VARIABLE_WRITE_ARCH_PROTOCOL are 

+  installed. DXE drivers that require read-only access or read/write access to volatile 

+  environment variables must have this architectural protocol in their dependency 

+  expressions. DXE drivers that require write access to nonvolatile environment 

+  variables must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency 

+  expressions.

 

   Copyright (c) 2006 - 2008, Intel Corporation                                                         

   All rights reserved. This program and the accompanying materials                          

diff --git a/MdePkg/Include/Protocol/VariableWrite.h b/MdePkg/Include/Protocol/VariableWrite.h
index 802026b739..d8d81076dc 100644
--- a/MdePkg/Include/Protocol/VariableWrite.h
+++ b/MdePkg/Include/Protocol/VariableWrite.h
@@ -1,13 +1,25 @@
 /** @file

   Variable Write Architectural Protocol as defined in PI Specification VOLUME 2 DXE

 

-  This code is used to produce the UEFI 2.0 runtime variable services

-

-  The SetVariable () UEFI 2.0 services may be updated to the EFI system table and the 

-  EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID protocol is registered with a NULL pointer.

-

-  No CRC of the EFI system table is required, as it is done in the DXE core.

-

+  This provides the services required to set nonvolatile environment variables. 

+  This protocol must be produced by a runtime DXE driver and may be consumed only 

+  by the DXE Foundation.

+

+  The DXE driver that produces this protocol must be a runtime driver. This driver 

+  may update the SetVariable() field of the UEFI Runtime Services Table.

+  

+  After the UEFI Runtime Services Table has been initialized, the driver must 

+  install the EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID on a new handle with a NULL 

+  interface pointer. The installation of this protocol informs the DXE Foundation 

+  that the write services for nonvolatile environment variables are now available 

+  and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services 

+  Table. The full complement of environment variable services are not available 

+  until both this protocol and EFI_VARIABLE_ARCH_PROTOCOL are installed. DXE drivers 

+  that require read-only access or read/write access to volatile environment variables

+  must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency expressions.

+  DXE drivers that require write access to nonvolatile environment variables must 

+  have this architectural protocol in their dependency expressions.  

+  

   Copyright (c) 2006 - 2008, Intel Corporation                                                         

   All rights reserved. This program and the accompanying materials                          

   are licensed and made available under the terms and conditions of the BSD License