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

diff --git a/MdePkg/Include/Protocol/Tcp4.h b/MdePkg/Include/Protocol/Tcp4.h
index fe37899f74c866471cc749ae55892f15f901007c..9fb8f5d1e3f66d1cff776e519f24c94829823942 100644 (file)
--- a/MdePkg/Include/Protocol/Tcp4.h
+++ b/MdePkg/Include/Protocol/Tcp4.h
@@ -33,7 +33,7 @@
 typedef struct _EFI_TCP4_PROTOCOL EFI_TCP4_PROTOCOL;\r
 \r
 typedef struct {\r
-  EFI_HANDLE        InstanceHandle;\r
+  EFI_HANDLE              InstanceHandle;\r
   EFI_IPv4_ADDRESS        LocalAddress;\r
   UINT16                  LocalPort;\r
   EFI_IPv4_ADDRESS        RemoteAddress;\r

diff --git a/MdePkg/Include/Protocol/Timer.h b/MdePkg/Include/Protocol/Timer.h
index cdf7b9bda9640989841d621f587d879ad5523cde..55ea8805342576fd9e3212493dd985f2fc000204 100644 (file)
--- 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;
 /**\r
   This function of this type is called when a timer interrupt fires.  This \r
   function executes at TPL_HIGH_LEVEL.  The DXE Core will register a funtion\r
-  of tyis type to be called for the timer interrupt, so it can know how much \r
+  of this type to be called for the timer interrupt, so it can know how much \r
   time has passed.  This information is used to signal timer based events.  \r
 \r
   @param  Time   Time since the last timer interrupt in 100 ns units. This will\r

diff --git a/MdePkg/Include/Protocol/UsbIo.h b/MdePkg/Include/Protocol/UsbIo.h
index 8f24f1a98c989f0e7e7749997be7cbe73f6ada41..fde139eb6e4cc3170f2b8ad88de242f6eb4c59fd 100644 (file)
--- 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.\r
 \r
   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
-                                device.\r
+  @param  DeviceEndpoint        The destination USB device endpoint to which the \r
+                                device request is being sent. DeviceEndpoint must \r
+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, \r
+                                otherwise EFI_INVALID_PARAMETER is returned. If \r
+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER \r
+                                is returned. The MSB of this parameter indicates \r
+                                the endpoint direction. The number “1” stands for \r
+                                an IN endpoint, and “0” stands for an OUT endpoint.\r
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                 device or received from USB device.\r
   @param  DataLength            The size, in bytes, of the data buffer specified by Data.\r
+                                On input, the size, in bytes, of the data buffer specified by Data.\r
+                                On output, the number of bytes that were actually transferred.\r
   @param  Timeout               Indicating the transfer should be completed within this time frame.\r
-                                The units are in milliseconds.\r
+                                The units are in milliseconds. If Timeout is 0, then the \r
+                                caller must wait for the function to be completed until \r
+                                EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
   @param  Status                This parameter indicates the USB transfer status.\r
 \r
   @retval EFI_SUCCESS           The bulk transfer has been successfully executed.\r
@@ -168,18 +178,28 @@ EFI_STATUS
   a fixed rate.\r
 \r
   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
-                                device.\r
+  @param  DeviceEndpoint        The destination USB device endpoint to which the \r
+                                device request is being sent. DeviceEndpoint must \r
+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, \r
+                                otherwise EFI_INVALID_PARAMETER is returned. If \r
+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER \r
+                                is returned. The MSB of this parameter indicates \r
+                                the endpoint direction. The number “1” stands for \r
+                                an IN endpoint, and “0” stands for an OUT endpoint.\r
   @param  IsNewTransfer         If TRUE, a new transfer will be submitted to USB controller. If\r
                                 FALSE, the interrupt transfer is deleted from the device's interrupt\r
                                 transfer queue.\r
   @param  PollingInterval       Indicates the periodic rate, in milliseconds, that the transfer is to be\r
-                                executed.\r
+                                executed.This parameter is required when IsNewTransfer is TRUE. The \r
+                                value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. \r
+                                The units are in milliseconds.\r
   @param  DataLength            Specifies the length, in bytes, of the data to be received from the\r
-                                USB device.\r
+                                USB device. This parameter is only required when IsNewTransfer is TRUE.\r
   @param  InterruptCallback     The Callback function. This function is called if the asynchronous\r
-                                interrupt transfer is completed.\r
-  @param  Context               Data passed to the InterruptCallback function.\r
+                                interrupt transfer is completed. This parameter is required \r
+                                when IsNewTransfer is TRUE.\r
+  @param  Context               Data passed to the InterruptCallback function. This is an optional \r
+                                parameter and may be NULL.\r
 \r
   @retval EFI_SUCCESS           The asynchronous USB transfer request transfer has been successfully executed.\r
   @retval EFI_DEVICE_ERROR      The asynchronous USB transfer request failed.\r
@@ -201,13 +221,22 @@ EFI_STATUS
   This function is used to manage a USB device with an interrupt transfer pipe.\r
 \r
   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
-                                device.\r
+  @param  DeviceEndpoint        The destination USB device endpoint to which the \r
+                                device request is being sent. DeviceEndpoint must \r
+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, \r
+                                otherwise EFI_INVALID_PARAMETER is returned. If \r
+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER \r
+                                is returned. The MSB of this parameter indicates \r
+                                the endpoint direction. The number “1” stands for \r
+                                an IN endpoint, and “0” stands for an OUT endpoint.\r
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                 device or received from USB device.\r
   @param  DataLength            On input, then size, in bytes, of the buffer Data. On output, the\r
                                 amount of data actually transferred.\r
-  @param  Timeout               The time out, in seconds, for this transfer.\r
+  @param  Timeout               The time out, in seconds, for this transfer. If Timeout is 0, \r
+                                then the caller must wait for the function to be completed \r
+                                until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the \r
+                                transfer is not completed in this time frame, then EFI_TIMEOUT is returned.\r
   @param  Status                This parameter indicates the USB transfer status.\r
 \r
   @retval EFI_SUCCESS           The sync interrupt transfer has been successfully executed.\r
@@ -232,8 +261,14 @@ EFI_STATUS
   transfer is typically used to transfer streaming data.\r
 \r
   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
-                                device.\r
+  @param  DeviceEndpoint        The destination USB device endpoint to which the \r
+                                device request is being sent. DeviceEndpoint must \r
+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, \r
+                                otherwise EFI_INVALID_PARAMETER is returned. If \r
+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER \r
+                                is returned. The MSB of this parameter indicates \r
+                                the endpoint direction. The number “1” stands for \r
+                                an IN endpoint, and “0” stands for an OUT endpoint.\r
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                 device or received from USB device.\r
   @param  DataLength            The size, in bytes, of the data buffer specified by Data.\r
@@ -261,12 +296,20 @@ EFI_STATUS
   transfer is typically used to transfer streaming data.\r
 \r
   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.\r
-  @param  DeviceEndpoint        A pointer to the USB device request that will be sent to the USB\r
-                                device.\r
+  @param  DeviceEndpoint        The destination USB device endpoint to which the \r
+                                device request is being sent. DeviceEndpoint must \r
+                                be between 0x01 and 0x0F or between 0x81 and 0x8F, \r
+                                otherwise EFI_INVALID_PARAMETER is returned. If \r
+                                the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER \r
+                                is returned. The MSB of this parameter indicates \r
+                                the endpoint direction. The number “1” stands for \r
+                                an IN endpoint, and “0” stands for an OUT endpoint.\r
   @param  Data                  A pointer to the buffer of data that will be transmitted to USB\r
                                 device or received from USB device.\r
   @param  DataLength            The size, in bytes, of the data buffer specified by Data.\r
-  @param  IsochronousCallback   The IsochronousCallback() function.\r
+                                This is an optional parameter and may be NULL.\r
+  @param  IsochronousCallback   The IsochronousCallback() function.This function is \r
+                                called if the requested isochronous transfer is completed.\r
   @param  Context               Data passed to the IsochronousCallback() function.\r
 \r
   @retval EFI_SUCCESS           The asynchronous isochronous transfer has been successfully submitted\r
@@ -389,7 +432,10 @@ EFI_STATUS
   @param  LangID                  The Language ID for the string being retrieved.\r
   @param  StringID                The ID of the string being retrieved.\r
   @param  String                  A pointer to a buffer allocated by this function with\r
-                                  AllocatePool() to store the string.\r
+                                  AllocatePool() to store the string.If this function \r
+                                  returns EFI_SUCCESS, it stores the string the caller \r
+                                  wants to get. The caller should release the string \r
+                                  buffer with FreePool() after the string is not used any more.\r
 \r
   @retval EFI_SUCCESS             The string was retrieved successfully.\r
   @retval EFI_NOT_FOUND           The string specified by LangID and StringID was not found.\r
@@ -410,6 +456,10 @@ EFI_STATUS
 \r
   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.\r
   @param  LangIDTable             Language ID for the string the caller wants to get.\r
+                                  This is a 16-bit ID defined by Microsoft. This \r
+                                  buffer pointer is allocated and maintained by \r
+                                  the USB Bus Driver, the caller should not modify \r
+                                  its contents.\r
   @param  TableSize               The size, in bytes, of the table LangIDTable.\r
 \r
   @retval EFI_SUCCESS             The support languages were retrieved successfully.\r

diff --git a/MdePkg/Include/Protocol/Variable.h b/MdePkg/Include/Protocol/Variable.h
index 9c09f1b49880e31cd97101f8805f229e580f5600..82c3bfc22553550439d224cbfc14802e5ca3656d 100644 (file)
--- a/MdePkg/Include/Protocol/Variable.h
+++ b/MdePkg/Include/Protocol/Variable.h
@@ -1,13 +1,24 @@
 /** @file\r
   Variable Architectural Protocol as defined in PI Specification VOLUME 2 DXE\r
 \r
-  This code is used to produce the UEFI 2.0 runtime variable services\r
-\r
-  The GetVariable (), GetNextVariableName (), and SetVariable () UEFI 2.0 \r
-  services are added to the EFI system table and the \r
-  EFI_VARIABLE_ARCH_PROTOCOL_GUID protocol is registered with a NULL pointer.\r
-\r
-  No CRC of the EFI system table is required, as it is done in the DXE core.\r
+  This provides the services required to get and set environment variables. This \r
+  protocol must be produced by a runtime DXE driver and may be consumed only by \r
+  the DXE Foundation. The DXE driver that produces this protocol must be a runtime \r
+  driver. This driver is responsible for initializing the GetVariable(), \r
+  GetNextVariableName(), and SetVariable() fields of the UEFI Runtime Services Table.\r
+\r
+  After the three fields of the UEFI Runtime Services Table have been initialized, \r
+  the driver must install the EFI_VARIABLE_ARCH_PROTOCOL_GUID on a new handle with \r
+  a NULL interface pointer. The installation of this protocol informs the DXE Foundation \r
+  that the read-only and the volatile environment variable related services are \r
+  now available and that the DXE Foundation must update the 32-bit CRC of the UEFI \r
+  Runtime Services Table. The full complement of environment variable services are \r
+  not available until both this protocol and EFI_VARIABLE_WRITE_ARCH_PROTOCOL are \r
+  installed. DXE drivers that require read-only access or read/write access to volatile \r
+  environment variables must have this architectural protocol in their dependency \r
+  expressions. DXE drivers that require write access to nonvolatile environment \r
+  variables must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency \r
+  expressions.\r
 \r
   Copyright (c) 2006 - 2008, Intel Corporation                                                         \r
   All rights reserved. This program and the accompanying materials                          \r

diff --git a/MdePkg/Include/Protocol/VariableWrite.h b/MdePkg/Include/Protocol/VariableWrite.h
index 802026b73930f5017b58b01d930b4f31865d0a73..d8d81076dc5b0a8bbb6283fe8ecf5c334764894c 100644 (file)
--- a/MdePkg/Include/Protocol/VariableWrite.h
+++ b/MdePkg/Include/Protocol/VariableWrite.h
@@ -1,13 +1,25 @@
 /** @file\r
   Variable Write Architectural Protocol as defined in PI Specification VOLUME 2 DXE\r
 \r
-  This code is used to produce the UEFI 2.0 runtime variable services\r
-\r
-  The SetVariable () UEFI 2.0 services may be updated to the EFI system table and the \r
-  EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID protocol is registered with a NULL pointer.\r
-\r
-  No CRC of the EFI system table is required, as it is done in the DXE core.\r
-\r
+  This provides the services required to set nonvolatile environment variables. \r
+  This protocol must be produced by a runtime DXE driver and may be consumed only \r
+  by the DXE Foundation.\r
+\r
+  The DXE driver that produces this protocol must be a runtime driver. This driver \r
+  may update the SetVariable() field of the UEFI Runtime Services Table.\r
+  \r
+  After the UEFI Runtime Services Table has been initialized, the driver must \r
+  install the EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID on a new handle with a NULL \r
+  interface pointer. The installation of this protocol informs the DXE Foundation \r
+  that the write services for nonvolatile environment variables are now available \r
+  and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services \r
+  Table. The full complement of environment variable services are not available \r
+  until both this protocol and EFI_VARIABLE_ARCH_PROTOCOL are installed. DXE drivers \r
+  that require read-only access or read/write access to volatile environment variables\r
+  must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency expressions.\r
+  DXE drivers that require write access to nonvolatile environment variables must \r
+  have this architectural protocol in their dependency expressions.  \r
+  \r
   Copyright (c) 2006 - 2008, 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