Add comments to describe the difference between code and spec to fix the bug #202409

[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / DataHub.h

diff --git a/IntelFrameworkPkg/Include/Protocol/DataHub.h b/IntelFrameworkPkg/Include/Protocol/DataHub.h
index a7ea34851e14fede691b8e5f1ae9d2f9f21917b8..2e9ef87099a2a5984a06009f39cff1f6603ef45a 100644 (file)
--- a/IntelFrameworkPkg/Include/Protocol/DataHub.h
+++ b/IntelFrameworkPkg/Include/Protocol/DataHub.h
@@ -3,28 +3,22 @@
   data and those wishing to be made aware of all information that\r
   has been logged.\r
 \r
   data and those wishing to be made aware of all information that\r
   has been logged.\r
 \r

-  For more information please look at Intel Platform Innovation\r
-  Framework for EFI Data Hub Specification.\r
-\r
-  Copyright (c) 2007, 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:  DataHub.h\r
-\r
-  @par Revision Reference:\r

   This protocol is defined in Framework for EFI Data Hub Specification.\r
   Version 0.9.\r
 \r
   This protocol is defined in Framework for EFI Data Hub Specification.\r
   Version 0.9.\r
 \r

+Copyright (c) 2007 - 2009, 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

 **/\r
 \r
 **/\r
 \r

-#ifndef _DATA_HUB_H_\r
-#define _DATA_HUB_H_\r
+#ifndef __DATA_HUB_H__\r
+#define __DATA_HUB_H__\r

 \r
 #include <PiDxe.h>\r
 \r
 \r
 #include <PiDxe.h>\r
 \r


@@ -81,7 +75,6 @@ typedef struct _EFI_DATA_HUB_PROTOCOL EFI_DATA_HUB_PROTOCOL;
   Logs a data record to the system event log.\r
 \r
   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.\r
   Logs a data record to the system event log.\r
 \r
   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.\r

-  @param  description\r

   @param  DataRecordGuid        A GUID that indicates the format of the data passed into RawData.\r
   @param  ProducerName          A GUID that indicates the identity of the caller to this API.\r
   @param  DataRecordClass       This class indicates the generic type of the data record.\r
   @param  DataRecordGuid        A GUID that indicates the format of the data passed into RawData.\r
   @param  ProducerName          A GUID that indicates the identity of the caller to this API.\r
   @param  DataRecordClass       This class indicates the generic type of the data record.\r


@@ -94,7 +87,7 @@ typedef struct _EFI_DATA_HUB_PROTOCOL EFI_DATA_HUB_PROTOCOL;
 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r

-(EFIAPI *EFI_DATA_HUB_LOG_DATA) (\r
+(EFIAPI *EFI_DATA_HUB_LOG_DATA)(\r

   IN  EFI_DATA_HUB_PROTOCOL   *This,\r
   IN  EFI_GUID                *DataRecordGuid,\r
   IN  EFI_GUID                *ProducerName,\r
   IN  EFI_DATA_HUB_PROTOCOL   *This,\r
   IN  EFI_GUID                *DataRecordGuid,\r
   IN  EFI_GUID                *ProducerName,\r


@@ -123,11 +116,13 @@ EFI_STATUS
                                 data records exist in the system.\r
   @retval EFI_OUT_OF_RESOURCES  Record was not returned due to lack\r
                                 of system resources.\r
                                 data records exist in the system.\r
   @retval EFI_OUT_OF_RESOURCES  Record was not returned due to lack\r
                                 of system resources.\r

-\r
+  @note: Inconsistent with specification here: \r
+         In Framework for EFI Data Hub Specification,Version 0.9, This definition is named as\r
+         EFI_DATA_HUB_GET_NEXT_DATA_RECORD. The inconsistance is remained for backward compatibility \r

 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r

-(EFIAPI *EFI_DATA_HUB_GET_NEXT_RECORD) (\r
+(EFIAPI *EFI_DATA_HUB_GET_NEXT_RECORD)(\r

   IN EFI_DATA_HUB_PROTOCOL    *This,\r
   IN OUT  UINT64              *MonotonicCount,\r
   IN  EFI_EVENT               *FilterDriver OPTIONAL,\r
   IN EFI_DATA_HUB_PROTOCOL    *This,\r
   IN OUT  UINT64              *MonotonicCount,\r
   IN  EFI_EVENT               *FilterDriver OPTIONAL,\r


@@ -153,11 +148,13 @@ EFI_STATUS
   @retval EFI_ALREADY_STARTED   FilterEvent was previously registered and cannot be registered again.\r
   @retval EFI_OUT_OF_RESOURCES  The filter driver event was not registered\r
                                 due to lack of system resources.\r
   @retval EFI_ALREADY_STARTED   FilterEvent was previously registered and cannot be registered again.\r
   @retval EFI_OUT_OF_RESOURCES  The filter driver event was not registered\r
                                 due to lack of system resources.\r

-\r
+  @note: Inconsistent with specification here: \r
+         In Framework for EFI Data Hub Specification,Version 0.9, This definition is named as\r
+         EFI_DATA_HUB_REGISTER_DATA_FILTER_DRIVER. The inconsistance is remained for backward compatibility \r

 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r

-(EFIAPI *EFI_DATA_HUB_REGISTER_FILTER_DRIVER) (\r
+(EFIAPI *EFI_DATA_HUB_REGISTER_FILTER_DRIVER)(\r

   IN EFI_DATA_HUB_PROTOCOL    *This,\r
   IN EFI_EVENT                FilterEvent,\r
   IN EFI_TPL                  FilterTpl,\r
   IN EFI_DATA_HUB_PROTOCOL    *This,\r
   IN EFI_EVENT                FilterEvent,\r
   IN EFI_TPL                  FilterTpl,\r


@@ -174,38 +171,41 @@ EFI_STATUS
 \r
   @retval EFI_SUCCESS           The filter driver represented by FilterEvent was shut off.\r
   @retval EFI_NOT_FOUND         FilterEvent did not exist.\r
 \r
   @retval EFI_SUCCESS           The filter driver represented by FilterEvent was shut off.\r
   @retval EFI_NOT_FOUND         FilterEvent did not exist.\r

-\r
+  @note: Inconsistent with specification here: \r
+         In Framework for EFI Data Hub Specification,Version 0.9, This definition is named as\r
+         EFI_DATA_HUB_UNREGISTER_DATA_FILTER_DRIVER. The inconsistance is remained for backward compatibility \r

 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r

-(EFIAPI *EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER) (\r
+(EFIAPI *EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER)(\r

   IN EFI_DATA_HUB_PROTOCOL    *This,\r
   IN EFI_EVENT                FilterEvent\r
   );\r
 \r
 /**\r
   IN EFI_DATA_HUB_PROTOCOL    *This,\r
   IN EFI_EVENT                FilterEvent\r
   );\r
 \r
 /**\r

-  @par Protocol Description:\r

   This protocol is used to log information and register filter drivers\r
   to receive data records.\r
   This protocol is used to log information and register filter drivers\r
   to receive data records.\r

-\r
-  @param LogData\r
-  Logs a data record.\r
-\r
-  @param GetNextDataRecord\r
-  Gets a data record. Used both to view the memory-based log and to\r
-  get information about which data records have been consumed by a filter driver.\r
-\r
-  @param RegisterFilterDriver\r
-  Allows the registration of an EFI event to act as a filter driver for all data records that are logged.\r
-\r
-  @param UnregisterFilterDriver\r
-  Used to remove a filter driver that was added with RegisterFilterDriver().\r
-\r

 **/\r
 struct _EFI_DATA_HUB_PROTOCOL {\r
 **/\r
 struct _EFI_DATA_HUB_PROTOCOL {\r

-  EFI_DATA_HUB_LOG_DATA                 LogData;\r
+  ///\r
+  /// Logs a data record.\r
+  ///\r
+  EFI_DATA_HUB_LOG_DATA                 LogData; \r
+  \r
+  ///\r
+  /// Gets a data record. Used both to view the memory-based log and to\r
+  /// get information about which data records have been consumed by a filter driver.\r
+  ///\r

   EFI_DATA_HUB_GET_NEXT_RECORD          GetNextRecord;\r
   EFI_DATA_HUB_GET_NEXT_RECORD          GetNextRecord;\r

+  \r
+  ///\r
+  /// Allows the registration of an EFI event to act as a filter driver for all data records that are logged.\r
+  ///\r

   EFI_DATA_HUB_REGISTER_FILTER_DRIVER   RegisterFilterDriver;\r
   EFI_DATA_HUB_REGISTER_FILTER_DRIVER   RegisterFilterDriver;\r

+  \r
+  ///\r
+  /// Used to remove a filter driver that was added with RegisterFilterDriver().\r
+  ///\r

   EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER UnregisterFilterDriver;\r
 };\r
 \r
   EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER UnregisterFilterDriver;\r
 };\r
 \r