From 5f597758e20f046a7a76e728370b99308cf2c8a0 Mon Sep 17 00:00:00 2001 From: lgao4 Date: Tue, 8 Jul 2008 13:29:42 +0000 Subject: Code scrube for MdeModule Definitions. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5428 6f19259b-4bc3-4df7-8a09-765794883524 --- MdeModulePkg/Include/Library/PlatDriOverLib.h | 339 ++++++++++++-------------- 1 file changed, 152 insertions(+), 187 deletions(-) (limited to 'MdeModulePkg/Include/Library/PlatDriOverLib.h') diff --git a/MdeModulePkg/Include/Library/PlatDriOverLib.h b/MdeModulePkg/Include/Library/PlatDriOverLib.h index e6a6faf..43d48a4 100644 --- a/MdeModulePkg/Include/Library/PlatDriOverLib.h +++ b/MdeModulePkg/Include/Library/PlatDriOverLib.h @@ -1,34 +1,29 @@ -/** @file - -Copyright (c) 2007, 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 -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - PlatDriOverLib.h - -Abstract: - - -**/ - -#ifndef _PLAT_DRI_OVER_LIB_H_ -#define _PLAT_DRI_OVER_LIB_H_ - -#include -#include -#include -#include -#include - -#include - +/** @file + + This library provides basic platform driver override functions. + +Copyright (c) 2007 - 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 +which accompanies this distribution. The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php + +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +#ifndef _PLAT_DRI_OVER_LIB_H_ +#define _PLAT_DRI_OVER_LIB_H_ + +#include +#include +#include +#include +#include + +#include + /** Install the Platform Driver Override Protocol, and ensure there is only one Platform Driver Override Protocol in the system. @@ -38,111 +33,67 @@ Abstract: @retval EFI_ALREADY_STARTED There has been a Platform Driver Override Protocol in the system, cannot install it again. - @retval Other Returned by InstallProtocolInterface - -**/ -EFI_STATUS -EFIAPI -InstallPlatformDriverOverrideProtocol ( - EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride - ); - + @retval EFI_SUCCESS The protocol is installed successfully. + +**/ +EFI_STATUS +EFIAPI +InstallPlatformDriverOverrideProtocol ( + EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride + ); + /** - Free all the mapping database memory resource and initialize the mapping list entry + Free all the mapping database memory resource and initialize the mapping list entry. @param MappingDataBase Mapping database list entry pointer @retval EFI_INVALID_PARAMETER mapping database list entry is NULL @retval EFI_SUCCESS Free success -**/ -EFI_STATUS -EFIAPI -FreeMappingDatabase ( - IN OUT LIST_ENTRY *MappingDataBase - ); - +**/ +EFI_STATUS +EFIAPI +FreeMappingDatabase ( + IN OUT LIST_ENTRY *MappingDataBase + ); + /** Read the environment variable(s) that contain the override mappings from Controller Device Path to a set of Driver Device Paths, and create the mapping database in memory with those variable info. - VariableLayout{ - // - // NotEnd indicate whether the variable is the last one, and has no subsequent variable need to load. - // Each variable has MaximumVariableSize limitation, so we maybe need multi variables to store - // large mapping infos. - // The variable(s) name rule is PlatDriOver, PlatDriOver1, PlatDriOver2, .... - // - UINT32 NotEnd; - // - // The entry which contains the mapping that Controller Device Path to a set of Driver Device Paths - // There are often multi mapping entries in a variable. - // - UINT32 SIGNATURE; //EFI_SIGNATURE_32('p','d','o','i') - UINT32 DriverNum; - EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath[]; - EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; - EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; - EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; - ...... - UINT32 SIGNATURE; - UINT32 DriverNum; - EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath[]; - EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; - EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; - EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; - ...... - } - typedef struct _PLATFORM_OVERRIDE_ITEM{ - UINTN Signature; //EFI_SIGNATURE_32('p','d','o','i') - LIST_ENTRY Link; - UINT32 DriverInfoNum; - EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath; - LIST_ENTRY DriverInfoList; //DRIVER_IMAGE_INFO List - } PLATFORM_OVERRIDE_ITEM; - typedef struct _DRIVER_IMAGE_INFO{ - UINTN Signature; //EFI_SIGNATURE_32('p','d','i','i') - LIST_ENTRY Link; - EFI_HANDLE ImageHandle; - EFI_DEVICE_PATH_PROTOCOL *DriverImagePath; - BOOLEAN UnLoadable; - BOOLEAN UnStartable; - } DRIVER_IMAGE_INFO; @param MappingDataBase Mapping database list entry pointer @retval EFI_INVALID_PARAMETER MappingDataBase pointer is null @retval EFI_NOT_FOUND Cannot find the 'PlatDriOver' NV variable @retval EFI_VOLUME_CORRUPTED The found NV variable is corrupted - @retval EFI_SUCCESS Create the mapping database in memory - successfully - -**/ -EFI_STATUS -EFIAPI -InitOverridesMapping ( - OUT LIST_ENTRY *MappingDataBase - ); - + @retval EFI_SUCCESS Create the mapping database in memory successfully + +**/ +EFI_STATUS +EFIAPI +InitOverridesMapping ( + OUT LIST_ENTRY *MappingDataBase + ); + /** - Save the memory mapping database into NV environment variable(s) + Save the memory mapping database into NV environment variable(s). @param MappingDataBase Mapping database list entry pointer @retval EFI_INVALID_PARAMETER MappingDataBase pointer is null @retval EFI_SUCCESS Save memory mapping database successfully -**/ -EFI_STATUS -EFIAPI -SaveOverridesMapping ( - IN LIST_ENTRY *MappingDataBase - ); - +**/ +EFI_STATUS +EFIAPI +SaveOverridesMapping ( + IN LIST_ENTRY *MappingDataBase + ); + /** Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database. - @param This A pointer to the - EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance. + @param This A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance. @param ControllerHandle The device handle of the controller to check if a driver override exists. @param DriverImageHandle On output, a pointer to the next driver handle. @@ -163,50 +114,56 @@ SaveOverridesMapping ( @retval EFI_SUCCESS The driver override for ControllerHandle was returned in DriverImagePath. -**/ -EFI_STATUS -EFIAPI -GetDriverFromMapping ( - IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL * This, - IN EFI_HANDLE ControllerHandle, - IN OUT EFI_HANDLE * DriverImageHandle, - IN LIST_ENTRY * MappingDataBase, - IN EFI_HANDLE CallerImageHandle - ); - -EFI_STATUS -EFIAPI -DeleteOverridesVariables ( - VOID - ); - +**/ +EFI_STATUS +EFIAPI +GetDriverFromMapping ( + IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL * This, + IN EFI_HANDLE ControllerHandle, + IN OUT EFI_HANDLE * DriverImageHandle, + IN LIST_ENTRY * MappingDataBase, + IN EFI_HANDLE CallerImageHandle + ); + +/** + Deletes all environment variable(s) that contain the override mappings from Controller Device Path to + a set of Driver Device Paths. + + @retval EFI_SUCCESS Delete all variable(s) successfully. +**/ +EFI_STATUS +EFIAPI +DeleteOverridesVariables ( + VOID + ); + /** Check mapping database whether already has the mapping info which records the input Controller to input DriverImage. - If has, the controller's total override driver number and input DriverImage's order number is return. - @param ControllerDevicePath The controller device path need to add a - override driver image item - @param DriverImageDevicePath The driver image device path need to be insert + @param ControllerDevicePath The controller device path is to be check. + @param DriverImageDevicePath The driver image device path is to be check. @param MappingDataBase Mapping database list entry pointer @param DriverInfoNum the controller's total override driver number - @param DriverImageNO The inserted order number - - @return EFI_INVALID_PARAMETER - @return EFI_NOT_FOUND - @return EFI_SUCCESS - -**/ -EFI_STATUS -EFIAPI -CheckMapping ( - IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath, - IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath, - IN LIST_ENTRY * MappingDataBase, - OUT UINT32 *DriverInfoNum, - OUT UINT32 *DriverImageNO - ); - + @param DriverImageNO The driver order number for the input DriverImage. + If the DriverImageDevicePath is NULL, DriverImageNO is not set. + + @retval EFI_INVALID_PARAMETER ControllerDevicePath or MappingDataBase is NULL. + @retval EFI_NOT_FOUND ControllerDevicePath is not found in MappingDataBase or + DriverImageDevicePath is not found in the found DriverImage Info list. + @retval EFI_SUCCESS The controller's total override driver number and + input DriverImage's order number is correctly return. +**/ +EFI_STATUS +EFIAPI +CheckMapping ( + IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath, + IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath, + IN LIST_ENTRY * MappingDataBase, + OUT UINT32 *DriverInfoNum, + OUT UINT32 *DriverImageNO + ); + /** Insert a driver image as a controller's override driver into the mapping database. The driver image's order number is indicated by DriverImageNO. @@ -215,50 +172,58 @@ CheckMapping ( override driver image item @param DriverImageDevicePath The driver image device path need to be insert @param MappingDataBase Mapping database list entry pointer - @param DriverImageNO The inserted order number - - @return EFI_INVALID_PARAMETER - @return EFI_ALREADY_STARTED - @return EFI_SUCCESS - -**/ -EFI_STATUS -EFIAPI -InsertDriverImage ( - IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath, - IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath, - IN LIST_ENTRY *MappingDataBase, - IN UINT32 DriverImageNO - ); - + @param DriverImageNO The inserted order number. If this number is taken, + the larger available number will be used. + + @retval EFI_INVALID_PARAMETER ControllerDevicePath is NULL, or DriverImageDevicePath is NULL + or MappingDataBase is NULL + @retval EFI_ALREADY_STARTED The input Controller to input DriverImage has been + recorded into the mapping database. + @retval EFI_SUCCESS The Controller and DriverImage are inserted into + the mapping database successfully. + +**/ +EFI_STATUS +EFIAPI +InsertDriverImage ( + IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath, + IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath, + IN LIST_ENTRY *MappingDataBase, + IN UINT32 DriverImageNO + ); + /** Delete a controller's override driver from the mapping database. - @param ControllerDevicePath The controller device path need to add a - override driver image item - @param DriverImageDevicePath The driver image device path need to be insert + @param ControllerDevicePath The controller device path will be deleted + when all drivers images on it are removed. + @param DriverImageDevicePath The driver image device path will be delete. + If NULL, all driver image will be delete. @param MappingDataBase Mapping database list entry pointer - @param DriverImageNO The inserted order number - - @return EFI_INVALID_PARAMETER - @return EFI_NOT_FOUND - @return EFI_SUCCESS - -**/ -EFI_STATUS -EFIAPI -DeleteDriverImage ( - IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath, - IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath, - IN LIST_ENTRY *MappingDataBase - ); - + + @retval EFI_INVALID_PARAMETER ControllerDevicePath is NULL, or MappingDataBase is NULL + @retval EFI_NOT_FOUND ControllerDevicePath is not found in MappingDataBase or + DriverImageDevicePath is not found in the found DriverImage Info list. + @retval EFI_SUCCESS Delete the specified driver successfully. + +**/ +EFI_STATUS +EFIAPI +DeleteDriverImage ( + IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath, + IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath, + IN LIST_ENTRY *MappingDataBase + ); + /** Get the first Binding protocol which has the specific image handle - @param Image Image handle + @param ImageHandle The Image handle + @param BindingHandle The BindingHandle of the found Driver Binding protocol. + If Binding protocol is not found, it is set to NULL. - @return Pointer into the Binding Protocol interface + @return Pointer into the Binding Protocol interface + @retval NULL The paramter is not valid or the binding protocol is not found. **/ EFI_DRIVER_BINDING_PROTOCOL * @@ -266,6 +231,6 @@ EFIAPI GetBindingProtocolFromImageHandle ( IN EFI_HANDLE ImageHandle, OUT EFI_HANDLE *BindingHandle - ); - -#endif + ); + +#endif -- cgit v1.1