From 8377875baae7bdbb89d6e63e8d74ace9a3f2cd59 Mon Sep 17 00:00:00 2001 From: klu2 Date: Sun, 28 Sep 2008 05:30:46 +0000 Subject: [PATCH] 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 --- MdePkg/Include/Protocol/Tcp4.h | 2 +- MdePkg/Include/Protocol/Timer.h | 2 +- MdePkg/Include/Protocol/UsbIo.h | 86 +++++++++++++++++++------ MdePkg/Include/Protocol/Variable.h | 25 +++++-- MdePkg/Include/Protocol/VariableWrite.h | 26 ++++++-- 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 -- 2.39.5