From 3354353d4d82fb12c073564ab41099ca75d02839 Mon Sep 17 00:00:00 2001 From: klu2 Date: Thu, 9 Oct 2008 18:09:49 +0000 Subject: [PATCH] Fix doxygen comment for structure and macro git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6093 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/Decompress.h | 11 -- MdePkg/Include/Protocol/DeviceIo.h | 38 ++----- MdePkg/Include/Protocol/DevicePathFromText.h | 7 -- MdePkg/Include/Protocol/DevicePathToText.h | 7 -- MdePkg/Include/Protocol/DevicePathUtilities.h | 24 ----- MdePkg/Include/Protocol/Dhcp4.h | 41 +------ MdePkg/Include/Protocol/DiskIo.h | 17 +-- MdePkg/Include/Protocol/DriverBinding.h | 100 ++++++++---------- MdePkg/Include/Protocol/DriverConfiguration.h | 19 +--- .../Include/Protocol/DriverConfiguration2.h | 22 +--- MdePkg/Include/Protocol/DriverDiagnostics.h | 14 +-- MdePkg/Include/Protocol/DriverDiagnostics2.h | 16 +-- MdePkg/Include/Protocol/DriverHealth.h | 9 -- .../Protocol/DriverSupportedEfiVersion.h | 18 ++-- 14 files changed, 90 insertions(+), 253 deletions(-) diff --git a/MdePkg/Include/Protocol/Decompress.h b/MdePkg/Include/Protocol/Decompress.h index 0cc9bb7e36..5b2291f177 100644 --- a/MdePkg/Include/Protocol/Decompress.h +++ b/MdePkg/Include/Protocol/Decompress.h @@ -113,17 +113,6 @@ EFI_STATUS @par Protocol Description: Provides a decompression service. - @param GetInfo - Given the compressed source buffer, this function retrieves the - size of the uncompressed destination buffer and the size of the - scratch buffer required to perform the decompression. It is the - caller's responsibility to allocate the destination buffer and the - scratch buffer prior to calling EFI_DECOMPRESS_PROTOCOL.Decompress(). - - @param Decompresss - Decompresses a compressed source buffer into an uncompressed - destination buffer. It is the caller's responsibility to allocate the - destination buffer and a scratch buffer prior to making this call. **/ struct _EFI_DECOMPRESS_PROTOCOL { EFI_DECOMPRESS_GET_INFO GetInfo; diff --git a/MdePkg/Include/Protocol/DeviceIo.h b/MdePkg/Include/Protocol/DeviceIo.h index 7b79d2355f..6ae0c23884 100644 --- a/MdePkg/Include/Protocol/DeviceIo.h +++ b/MdePkg/Include/Protocol/DeviceIo.h @@ -217,39 +217,19 @@ EFI_STATUS @par Protocol Description: This protocol provides the basic Memory, I/O, and PCI interfaces that are used to abstract accesses to devices. - - @param Mem - Allows reads and writes to memory mapped I/O space. - - @param Io - Allows reads and writes to I/O space. - - @param Pci - Allows reads and writes to PCI configuration space. - - @param Map - Provides the device specific addresses needed to access system memory for DMA. - - @param PciDevicePath - Provides an EFI Device Path for a PCI device with the given PCI - configuration space address. - - @param Unmap - Releases any resources allocated by Map(). - - @param AllocateBuffer - Allocates pages that are suitable for a common buffer mapping. - - @param Flush - Flushes any posted write data to the device. - - @param FreeBuffer - Free pages that were allocated with AllocateBuffer(). - **/ struct _EFI_DEVICE_IO_PROTOCOL { + /// + /// Allows reads and writes to memory mapped I/O space. + /// EFI_IO_ACCESS Mem; + /// + /// Allows reads and writes to I/O space. + /// EFI_IO_ACCESS Io; + /// + /// Allows reads and writes to PCI configuration space. + /// EFI_IO_ACCESS Pci; EFI_IO_MAP Map; EFI_PCI_DEVICE_PATH PciDevicePath; diff --git a/MdePkg/Include/Protocol/DevicePathFromText.h b/MdePkg/Include/Protocol/DevicePathFromText.h index 7c4a161483..327c5e27a3 100644 --- a/MdePkg/Include/Protocol/DevicePathFromText.h +++ b/MdePkg/Include/Protocol/DevicePathFromText.h @@ -64,13 +64,6 @@ EFI_DEVICE_PATH_PROTOCOL* /** @par Protocol Description: This protocol converts text to device paths and device nodes. - - @param ConvertTextToDeviceNode - Convert text to a device node. - - @param ConvertTextToDevicePath - Convert text to a device path - **/ typedef struct { EFI_DEVICE_PATH_FROM_TEXT_NODE ConvertTextToDeviceNode; diff --git a/MdePkg/Include/Protocol/DevicePathToText.h b/MdePkg/Include/Protocol/DevicePathToText.h index 4a8353181f..853e43e133 100644 --- a/MdePkg/Include/Protocol/DevicePathToText.h +++ b/MdePkg/Include/Protocol/DevicePathToText.h @@ -75,13 +75,6 @@ CHAR16* /** @par Protocol Description: This protocol converts device paths and device nodes to text. - - @param ConvertTextToDeviceNode - Convert the device node to text. - - @param ConvertTextToDevicePath - Convert the device path to text. - **/ typedef struct { EFI_DEVICE_PATH_TO_TEXT_NODE ConvertDeviceNodeToText; diff --git a/MdePkg/Include/Protocol/DevicePathUtilities.h b/MdePkg/Include/Protocol/DevicePathUtilities.h index 44e88ee315..8d98add591 100644 --- a/MdePkg/Include/Protocol/DevicePathUtilities.h +++ b/MdePkg/Include/Protocol/DevicePathUtilities.h @@ -173,30 +173,6 @@ BOOLEAN /** @par Protocol Description: This protocol is used to creates and manipulates device paths and device nodes. - - @param GetDevicePathSize - Returns the size of the specified device path, in bytes. - - @param DuplicateDevicePath - Duplicates a device path structure. - - @param AppendDeviceNode - Appends the device node to the specified device path. - - @param AppendDevicePath - Appends the device path to the specified device path. - - @param AppendDevicePathInstance - Appends a device path instance to another device path. - - @param GetNextDevicePathInstance - Retrieves the next device path instance from a device path data structure. - - @param IsDevicePathMultiInstance - Returns TRUE if this is a multi-instance device path. - - @param CreateDeviceNode - Allocates memory for a device node with the specified type and sub-type. **/ typedef struct { EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE GetDevicePathSize; diff --git a/MdePkg/Include/Protocol/Dhcp4.h b/MdePkg/Include/Protocol/Dhcp4.h index e7fc60ecde..2031f2b5da 100644 --- a/MdePkg/Include/Protocol/Dhcp4.h +++ b/MdePkg/Include/Protocol/Dhcp4.h @@ -49,11 +49,11 @@ typedef struct { UINT32 Xid; UINT16 Seconds; UINT16 Reserved; - EFI_IPv4_ADDRESS ClientAddr; //Client IP address from client - EFI_IPv4_ADDRESS YourAddr; //Client IP address from server - EFI_IPv4_ADDRESS ServerAddr; //IP address of next server in bootstrap - EFI_IPv4_ADDRESS GatewayAddr; //Relay agent IP address - UINT8 ClientHwAddr[16]; //Client hardware address + EFI_IPv4_ADDRESS ClientAddr; ///< Client IP address from client + EFI_IPv4_ADDRESS YourAddr; ///< Client IP address from server + EFI_IPv4_ADDRESS ServerAddr; ///< IP address of next server in bootstrap + EFI_IPv4_ADDRESS GatewayAddr; ///< Relay agent IP address + UINT8 ClientHwAddr[16]; ///< Client hardware address CHAR8 ServerName[64]; CHAR8 BootFileName[128]; }EFI_DHCP4_HEADER; @@ -415,37 +415,6 @@ EFI_STATUS @par Protocol Description: This protocol is used to collect configuration information for the EFI IPv4 Protocol drivers and to provide DHCPv4 server and PXE boot server discovery services. - - @param GetModeData - Gets the EFI DHCPv4 Protocol driver status and operational data. - - @param Configure - Initializes, changes, or resets operational settings for the EFI - DHCPv4 Protocol driver. - - @param Start - Starts the DHCP configuration process. - - @param RenewRebind - Tries to manually extend the lease time by sending a request packet. - - @param Release - Releases the current configuration and returns the EFI DHCPv4 - Protocol driver to the initial state. - - @param Stop - Stops the DHCP configuration process no matter what state the - driver is in. After being stopped, this driver will not automatically - communicate with the DHCP server. - - @param Build - Puts together a DHCP or PXE packet. - - @param TransmitReceive - Transmits a DHCP or PXE packet and waits for response packets. - - @param Parse - Parses the packed DHCP or PXE option data. **/ struct _EFI_DHCP4_PROTOCOL { EFI_DHCP4_GET_MODE_DATA GetModeData; diff --git a/MdePkg/Include/Protocol/DiskIo.h b/MdePkg/Include/Protocol/DiskIo.h index fbf4384874..23c7258434 100644 --- a/MdePkg/Include/Protocol/DiskIo.h +++ b/MdePkg/Include/Protocol/DiskIo.h @@ -101,20 +101,13 @@ EFI_STATUS /** @par Protocol Description: This protocol is used to abstract Block I/O interfaces. - - @param Revision - The revision to which the disk I/O interface adheres. All future - revisions must be backwards compatible. If a future version is not - backwards compatible, it is not the same GUID. - - @param ReadDisk - Reads data from the disk. - - @param WriteDisk - Writes data to the disk. - **/ struct _EFI_DISK_IO_PROTOCOL { + /// + /// The revision to which the disk I/O interface adheres. All future + /// revisions must be backwards compatible. If a future version is not + /// backwards compatible, it is not the same GUID. + /// UINT64 Revision; EFI_DISK_READ ReadDisk; EFI_DISK_WRITE WriteDisk; diff --git a/MdePkg/Include/Protocol/DriverBinding.h b/MdePkg/Include/Protocol/DriverBinding.h index 6f6ddf6ad1..43fc16593b 100644 --- a/MdePkg/Include/Protocol/DriverBinding.h +++ b/MdePkg/Include/Protocol/DriverBinding.h @@ -30,7 +30,12 @@ typedef struct _EFI_DRIVER_BINDING_PROTOCOL EFI_DRIVER_BINDING_PROTOCOL; /** - Test to see if this driver supports ControllerHandle. + Test to see if this driver supports ControllerHandle. This service + is called by the EFI boot service ConnectController(). In + order to make drivers as small as possible, there are a few calling + restrictions for this service. ConnectController() must + follow these calling restrictions. If any other agent wishes to call + Supported() it must also follow these calling restrictions. @param This Protocol instance pointer. @param ControllerHandle Handle of device to test @@ -51,7 +56,12 @@ EFI_STATUS ); /** - Start this driver on ControllerHandle. + Start this driver on ControllerHandle. This service is called by the + EFI boot service ConnectController(). In order to make + drivers as small as possible, there are a few calling restrictions for + this service. ConnectController() must follow these + calling restrictions. If any other agent wishes to call Start() it + must also follow these calling restrictions. @param This Protocol instance pointer. @param ControllerHandle Handle of device to bind driver to @@ -72,8 +82,13 @@ EFI_STATUS ); /** - Stop this driver on ControllerHandle. - + Stop this driver on ControllerHandle. This service is called by the + EFI boot service DisconnectController(). In order to + make drivers as small as possible, there are a few calling + restrictions for this service. DisconnectController() + must follow these calling restrictions. If any other agent wishes + to call Stop() it must also follow these calling restrictions. + @param This Protocol instance pointer. @param ControllerHandle Handle of device to stop driver on @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of @@ -100,63 +115,40 @@ EFI_STATUS @par Protocol Description: This protocol provides the services required to determine if a driver supports a given controller. If a controller is supported, then it also provides routines to start and stop the controller. - - @param Supported - Tests to see if this driver supports a given controller. This service - is called by the EFI boot service ConnectController(). In - order to make drivers as small as possible, there are a few calling - restrictions for this service. ConnectController() must - follow these calling restrictions. If any other agent wishes to call - Supported() it must also follow these calling restrictions. - - - @param Start - Starts a controller using this driver. This service is called by the - EFI boot service ConnectController(). In order to make - drivers as small as possible, there are a few calling restrictions for - this service. ConnectController() must follow these - calling restrictions. If any other agent wishes to call Start() it - must also follow these calling restrictions. - - @param Stop - Stops a controller using this driver. This service is called by the - EFI boot service DisconnectController(). In order to - make drivers as small as possible, there are a few calling - restrictions for this service. DisconnectController() - must follow these calling restrictions. If any other agent wishes - to call Stop() it must also follow these calling restrictions. - - @param Version - The version number of the UEFI driver that produced the - EFI_DRIVER_BINDING_PROTOCOL. This field is used by - the EFI boot service ConnectController() to determine - the order that driver's Supported() service will be used when - a controller needs to be started. EFI Driver Binding Protocol - instances with higher Version values will be used before ones - with lower Version values. The Version values of 0x0- - 0x0f and 0xfffffff0-0xffffffff are reserved for - platform/OEM specific drivers. The Version values of 0x10- - 0xffffffef are reserved for IHV-developed drivers. - - @param ImageHandle - The image handle of the UEFI driver that produced this instance - of the EFI_DRIVER_BINDING_PROTOCOL. - - @param DriverBindingHandle - The handle on which this instance of the - EFI_DRIVER_BINDING_PROTOCOL is installed. In most - cases, this is the same handle as ImageHandle. However, for - UEFI drivers that produce more than one instance of the - EFI_DRIVER_BINDING_PROTOCOL, this value may not be - the same as ImageHandle. - **/ struct _EFI_DRIVER_BINDING_PROTOCOL { EFI_DRIVER_BINDING_SUPPORTED Supported; EFI_DRIVER_BINDING_START Start; EFI_DRIVER_BINDING_STOP Stop; + + /// + /// The version number of the UEFI driver that produced the + /// EFI_DRIVER_BINDING_PROTOCOL. This field is used by + /// the EFI boot service ConnectController() to determine + /// the order that driver's Supported() service will be used when + /// a controller needs to be started. EFI Driver Binding Protocol + /// instances with higher Version values will be used before ones + /// with lower Version values. The Version values of 0x0- + /// 0x0f and 0xfffffff0-0xffffffff are reserved for + /// platform/OEM specific drivers. The Version values of 0x10- + /// 0xffffffef are reserved for IHV-developed drivers. + /// UINT32 Version; + + /// + /// The image handle of the UEFI driver that produced this instance + /// of the EFI_DRIVER_BINDING_PROTOCOL. + /// EFI_HANDLE ImageHandle; + + /// + /// The handle on which this instance of the + /// EFI_DRIVER_BINDING_PROTOCOL is installed. In most + /// cases, this is the same handle as ImageHandle. However, for + /// UEFI drivers that produce more than one instance of the + /// EFI_DRIVER_BINDING_PROTOCOL, this value may not be + /// the same as ImageHandle. + /// EFI_HANDLE DriverBindingHandle; }; diff --git a/MdePkg/Include/Protocol/DriverConfiguration.h b/MdePkg/Include/Protocol/DriverConfiguration.h index 7c7eca4531..172b61ef0c 100644 --- a/MdePkg/Include/Protocol/DriverConfiguration.h +++ b/MdePkg/Include/Protocol/DriverConfiguration.h @@ -24,7 +24,6 @@ { \ 0x107a772b, 0xd5e1, 0x11d4, {0x9a, 0x46, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \ } - typedef struct _EFI_DRIVER_CONFIGURATION_PROTOCOL EFI_DRIVER_CONFIGURATION_PROTOCOL; @@ -153,24 +152,16 @@ EFI_STATUS @par Protocol Description: Used to set configuration options for a controller that an EFI Driver is managing. - @param SetOptions Allows the use to set drivers specific configuration - options for a controller that the driver is currently managing. - - @param OptionsValid Tests to see if a controller's current configuration - options are valid. - - @param ForceDefaults Forces a driver to set the default configuration options - for a controller. - - @param SupportedLanguages A Null-terminated ASCII string that contains one or more - ISO 639-2 language codes. This is the list of language - codes that this protocol supports. - **/ struct _EFI_DRIVER_CONFIGURATION_PROTOCOL { EFI_DRIVER_CONFIGURATION_SET_OPTIONS SetOptions; EFI_DRIVER_CONFIGURATION_OPTIONS_VALID OptionsValid; EFI_DRIVER_CONFIGURATION_FORCE_DEFAULTS ForceDefaults; + /// + /// A Null-terminated ASCII string that contains one or more + /// ISO 639-2 language codes. This is the list of language + /// codes that this protocol supports. + /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/DriverConfiguration2.h b/MdePkg/Include/Protocol/DriverConfiguration2.h index 4ae1d0235a..30b9d7ff98 100644 --- a/MdePkg/Include/Protocol/DriverConfiguration2.h +++ b/MdePkg/Include/Protocol/DriverConfiguration2.h @@ -160,32 +160,18 @@ EFI_STATUS @par Protocol Description: Used to set configuration options for a controller that an EFI Driver is managing. - - @param SetOptions Allows the use to set drivers specific configuration - options for a controller that the driver is currently managing. - - @param OptionsValid Tests to see if a controller's current configuration - options are valid. - - @param ForceDefaults Forces a driver to set the default configuration options - for a controller. - - @param SupportedLanguages A Null-terminated ASCII string that - contains one or more RFC 3066 - language codes. This is the list - of language codes that this - protocol supports. - **/ struct _EFI_DRIVER_CONFIGURATION2_PROTOCOL { EFI_DRIVER_CONFIGURATION2_SET_OPTIONS SetOptions; EFI_DRIVER_CONFIGURATION2_OPTIONS_VALID OptionsValid; EFI_DRIVER_CONFIGURATION2_FORCE_DEFAULTS ForceDefaults; + /// + /// A Null-terminated ASCII string that contains one or more RFC 3066 + /// language codes. This is the list of language codes that this protocol supports. + /// CHAR8 *SupportedLanguages; }; - - extern EFI_GUID gEfiDriverConfiguration2ProtocolGuid; #endif diff --git a/MdePkg/Include/Protocol/DriverDiagnostics.h b/MdePkg/Include/Protocol/DriverDiagnostics.h index 6c794be50d..1bd2383dd3 100644 --- a/MdePkg/Include/Protocol/DriverDiagnostics.h +++ b/MdePkg/Include/Protocol/DriverDiagnostics.h @@ -97,24 +97,18 @@ EFI_STATUS OUT CHAR16 **Buffer ); - -// -// - /** Interface structure for the Driver Diagnostics Protocol. @par Protocol Description: Used to perform diagnostics on a controller that an EFI Driver is managing. - - @param RunDiagnostics Runs diagnostics on a controller. - @param SupportedLanguages A Null-terminated ASCII string that contains one or more - ISO 639-2 language codes. This is the list of language - codes that this protocol supports. - **/ struct _EFI_DRIVER_DIAGNOSTICS_PROTOCOL { EFI_DRIVER_DIAGNOSTICS_RUN_DIAGNOSTICS RunDiagnostics; + /// + /// A Null-terminated ASCII string that contains one or more RFC 3066 + /// language codes. This is the list of language codes that this protocol supports. + /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/DriverDiagnostics2.h b/MdePkg/Include/Protocol/DriverDiagnostics2.h index 99ae5d0807..f8bd6206b2 100644 --- a/MdePkg/Include/Protocol/DriverDiagnostics2.h +++ b/MdePkg/Include/Protocol/DriverDiagnostics2.h @@ -91,26 +91,18 @@ EFI_STATUS OUT CHAR16 **Buffer ); - -// -// - /** Interface structure for the Driver Diagnostics2 Protocol. @par Protocol Description: Used to perform diagnostics on a controller that an EFI Driver is managing. - - @param RunDiagnostics Runs diagnostics on a controller. - @param SupportedLanguages A Null-terminated ASCII string that - contains one or more RFC 3066 - language codes. This is the list - of language codes that this - protocol supports. - **/ struct _EFI_DRIVER_DIAGNOSTICS2_PROTOCOL { EFI_DRIVER_DIAGNOSTICS2_RUN_DIAGNOSTICS RunDiagnostics; + /// + /// A Null-terminated ASCII string that contains one or more RFC 3066 + /// language codes. This is the list of language codes that this protocol supports. + /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/DriverHealth.h b/MdePkg/Include/Protocol/DriverHealth.h index 2b889023f5..f7bf0b857e 100644 --- a/MdePkg/Include/Protocol/DriverHealth.h +++ b/MdePkg/Include/Protocol/DriverHealth.h @@ -232,15 +232,6 @@ EFI_STATUS configuration changes to take affect. Figure 2-1 below shows all the possible health states of a controller and the legal transitions between the health states. - @param GetHealthStatus Retrieves the health status of a controller in the - platform. This function can also optionally return - warning messages, error messages, and a set of HII - Forms that may be repair a controller that is not - properly configured. - @param Repair Performs a repair operation on a controller in the - platform. This function can optionally report repair - progress information back to the platform. - **/ struct _EFI_DRIVER_HEALTH_PROTOCOL { EFI_DRIVER_HEALTH_GET_HEALTH_STATUS GetHealthStatus; diff --git a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h index 3bd3e00bae..3592198cf7 100644 --- a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h +++ b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h @@ -29,19 +29,17 @@ specification it conforms to. This protocol must be placed on the drivers image handle when the driver's entry point is called. - - @param Length The size, in bytes, of the entire structure. - Future versions of this specification may grow - the size of the structure. - - @param FirmwareVersion The version of the EFI specification - that this driver conforms to. - EFI_2_10_SYSTEM_TABLE_REVISION for this - version of this specification. - **/ typedef struct _EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL { + /// + /// The size, in bytes, of the entire structure. Future versions of this + /// specification may grow the size of the structure. + /// UINT32 Length; + /// + /// The version of the EFI specification that this driver conforms to. + /// EFI_2_10_SYSTEM_TABLE_REVISION for this version of this specification. + /// UINT32 FirmwareVersion; } EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL; -- 2.39.5