diff options
author | gikidy <gikidy@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-11-19 10:00:35 +0000 |
---|---|---|
committer | gikidy <gikidy@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-11-19 10:00:35 +0000 |
commit | d80b2f71fc3c303fa8d0f5010a33b690b1285e7c (patch) | |
tree | f63c97a6fb097bef55776fbca290785d78a3315f /MdePkg/Include/Library | |
parent | 6a0e332d933a6fd20d9ff417c6b59a7b438708ee (diff) | |
download | edk2-platforms-d80b2f71fc3c303fa8d0f5010a33b690b1285e7c.tar.xz |
Synchronize the MdePkg\Include\Library\BaseMemoryLib.h,
CacheMaintenance.h,CpuLib.h,DebugLib.h,DevicePathLib.h with the MDE_Library_Spec.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6629 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdePkg/Include/Library')
-rw-r--r-- | MdePkg/Include/Library/BaseMemoryLib.h | 8 | ||||
-rw-r--r-- | MdePkg/Include/Library/CacheMaintenanceLib.h | 5 | ||||
-rw-r--r-- | MdePkg/Include/Library/CpuLib.h | 5 | ||||
-rw-r--r-- | MdePkg/Include/Library/DebugLib.h | 5 | ||||
-rw-r--r-- | MdePkg/Include/Library/DevicePathLib.h | 146 |
5 files changed, 154 insertions, 15 deletions
diff --git a/MdePkg/Include/Library/BaseMemoryLib.h b/MdePkg/Include/Library/BaseMemoryLib.h index abc3bb209a..973bc2b635 100644 --- a/MdePkg/Include/Library/BaseMemoryLib.h +++ b/MdePkg/Include/Library/BaseMemoryLib.h @@ -1,5 +1,9 @@ /** @file
- Provides copy memory, fill memory, zero memory, and GUID functions.
+ Provides copy memory, fill memory, zero memory, and GUID functions.
+
+ The Base Memory Library provides optimized implementions for common memory-based operations.
+ These functions should be used in place of coding your own loops to do equivalent common functions.
+ This allows optimized library implementations to help increase performance.
Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -47,7 +51,7 @@ CopyMem ( @param Buffer Memory to set.
@param Length Number of bytes to set.
- @param Value Value of the set operation.
+ @param Value Value with which to fill Length bytes of Buffer.
@return Buffer.
diff --git a/MdePkg/Include/Library/CacheMaintenanceLib.h b/MdePkg/Include/Library/CacheMaintenanceLib.h index b5b3dd3d51..a5c690f804 100644 --- a/MdePkg/Include/Library/CacheMaintenanceLib.h +++ b/MdePkg/Include/Library/CacheMaintenanceLib.h @@ -1,6 +1,9 @@ /** @file
Provides services to maintain instruction and data caches.
-
+
+ The Cache Maintenance Library provides abstractions for basic processor cache operations.
+ It removes the need to use assembly in C code.
+
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
diff --git a/MdePkg/Include/Library/CpuLib.h b/MdePkg/Include/Library/CpuLib.h index ec36b41af2..b54dd26991 100644 --- a/MdePkg/Include/Library/CpuLib.h +++ b/MdePkg/Include/Library/CpuLib.h @@ -1,6 +1,11 @@ /** @file
Provides CPU architecture specific functions that can not be defined
in the Base Library due to dependencies on the PAL Library
+
+ The CPU Library provides services to flush CPU TLBs and place the CPU in a sleep state.
+ The implementation of these services on Itanium CPUs requires the use of PAL Calls.
+ PAL Calls require PEI and DXE specific mechanisms to look up PAL Entry Point.
+ As a result, these services could not be defined in the Base Library.
Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
diff --git a/MdePkg/Include/Library/DebugLib.h b/MdePkg/Include/Library/DebugLib.h index 7465abb24d..51da314ea2 100644 --- a/MdePkg/Include/Library/DebugLib.h +++ b/MdePkg/Include/Library/DebugLib.h @@ -1,6 +1,9 @@ /** @file
Provides services to print debug and assert messages to a debug output device.
-
+
+ The Debug library supports debug print and asserts based on a combination of macros and code.
+ The debug library can be turned on and off so that the debug code does not increase the size of an image.
+
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
diff --git a/MdePkg/Include/Library/DevicePathLib.h b/MdePkg/Include/Library/DevicePathLib.h index 05e98a4d3d..891b5d657a 100644 --- a/MdePkg/Include/Library/DevicePathLib.h +++ b/MdePkg/Include/Library/DevicePathLib.h @@ -1,6 +1,11 @@ /** @file
Provides library functions to construct and parse UEFI Device Paths.
+ This library provides defines, macros, and functions to help create and parse
+ EFI_DEVICE_PATH_PROTOCOL structures. The macros that help create and parse device
+ path nodes make use of the ReadUnaligned16() and WriteUnaligned16() functions from
+ the Base Library, so this library class has an implied dependency on the Base Library.
+
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
@@ -18,15 +23,121 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include <Library/BaseLib.h>
#define END_DEVICE_PATH_LENGTH (sizeof (EFI_DEVICE_PATH_PROTOCOL))
-#define DevicePathNodeLength(Node) ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0])
-#define NextDevicePathNode(Node) ((EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node)))
+
+/**
+ Macro that returns the Type field of a device path node.
+
+ Returns the Type field of the device path node specified by Node.
+
+ @param Node A pointer to a device path node data structure.
+
+ @return The Type field of the device path node specified by Node.
+
+**/
#define DevicePathType(Node) (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Type)
+
+/**
+ Macro that returns the SubType field of a device path node.
+
+ Returns the SubType field of the device path node specified by Node.
+
+ @param Node A pointer to a device path node data structure.
+
+ @return The SubType field of the device path node specified by Node.
+
+**/
#define DevicePathSubType(Node) (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->SubType)
+
+/**
+ Macro that returns the 16-bit Length field of a device path node.
+
+ Returns the 16-bit Length field of the device path node specified by Node.
+
+ @param Node A pointer to a device path node data structure.
+
+ @return The 16-bit Length field of the device path node specified by Node.
+
+**/
+#define DevicePathNodeLength(Node) ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0])
+
+/**
+ Macro that returns a pointer to the next node in a device path.
+
+ Returns a pointer to the device path node that follows the device path node specified by Node.
+
+ @param Node A pointer to a device path node data structure.
+
+ @return a pointer to the device path node that follows the device path node specified by Node.
+
+**/
+#define NextDevicePathNode(Node) ((EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node)))
+
+/**
+ Macro that determines if a device path node is an end node of a device path.
+ This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path.
+
+ Determines if the device path node specified by Node is an end node of a device path.
+ This includes nodes that are the end of a device path instance and nodes that are the
+ end of an entire device path. If Node represents an end node of a device path,
+ then TRUE is returned. Otherwise, FALSE is returned.
+
+ @param Node A pointer to a device path node data structure.
+
+ @retval TRUE The device path node specified by Node is an end node of a device path.
+ @retval FALSE The device path node specified by Node is not an end node of a device path.
+
+**/
#define IsDevicePathEndType(Node) ((DevicePathType (Node) & 0x7f) == END_DEVICE_PATH_TYPE)
+
+/**
+ Macro that determines if a device path node is an end node of an entire device path.
+
+ Determines if a device path node specified by Node is an end node of an entire device path.
+ If Node represents the end of an entire device path, then TRUE is returned. Otherwise, FALSE is returned.
+
+ @param Node A pointer to a device path node data structure.
+
+ @retval TRUE The device path node specified by Node is the end of an entire device path.
+ @retval FALSE The device path node specified by Node is not the end of an entire device path.
+
+**/
#define IsDevicePathEnd(Node) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_ENTIRE_DEVICE_PATH_SUBTYPE)
+
+/**
+ Macro that determines if a device path node is an end node of a device path instance.
+
+ Determines if a device path node specified by Node is an end node of a device path instance.
+ If Node represents the end of a device path instance, then TRUE is returned. Otherwise, FALSE is returned.
+
+ @param Node A pointer to a device path node data structure.
+
+ @retval TRUE The device path node specified by Node is the end of a device path instance.
+ @retval FALSE The device path node specified by Node is not the end of a device path instance.
+
+**/
#define IsDevicePathEndInstance(Node) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_INSTANCE_DEVICE_PATH_SUBTYPE)
+/**
+ Macro that sets the length, in bytes, of a device path node.
+
+ Sets the length of the device path node specified by Node to the value specified by Length. Length is returned.
+
+ @param Node A pointer to a device path node data structure.
+ @param Length The length, in bytes, of the device path node.
+
+ @return Length
+
+**/
#define SetDevicePathNodeLength(Node,NodeLength) WriteUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0], (UINT16)(NodeLength))
+
+/**
+ Macro that fills in all the fields of a device path node that is the end of an entire device path.
+
+ Fills in all the fields of a device path node specified by Node so Node represents the end of an entire device path.
+
+ @param Node A pointer to a device path node data structure.
+
+**/
#define SetDevicePathEndNode(Node) { \
DevicePathType (Node) = END_DEVICE_PATH_TYPE; \
DevicePathSubType (Node) = END_ENTIRE_DEVICE_PATH_SUBTYPE; \
@@ -40,8 +151,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned.
@param DevicePath A pointer to a device path data structure.
-
- @return The size of a device path in bytes.
+
+ @retval 0 If DevicePath is NULL.
+ @retval Others The size of a device path in bytes.
**/
UINTN
@@ -57,11 +169,14 @@ GetDevicePathSize ( DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the
contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
is returned. Otherwise, NULL is returned.
+ The memory for the new device path is allocated from EFI boot services memory.
+ It is the responsibility of the caller to free the memory allocated.
@param DevicePath A pointer to a device path data structure.
- @return A pointer to the duplicated device path.
-
+ @retval NULL If DevicePath is NULL.
+ @retval Others A pointer to the duplicated device path.
+
**/
EFI_DEVICE_PATH_PROTOCOL *
EFIAPI
@@ -85,8 +200,10 @@ DuplicateDevicePath ( @param FirstDevicePath A pointer to a device path data structure.
@param SecondDevicePath A pointer to a device path data structure.
-
- @return A pointer to the new device path.
+
+ @retval NULL If there is not enough memory for the newly allocated buffer.
+ @retval Others A pointer to the new device path if success.
+ Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
**/
EFI_DEVICE_PATH_PROTOCOL *
@@ -114,7 +231,11 @@ AppendDevicePath ( @param DevicePath A pointer to a device path data structure.
@param DevicePathNode A pointer to a single device path node.
- @return A pointer to the new device path.
+ @retval NULL If there is not enough memory for the new device path.
+ @retval Others A pointer to the new device path if success.
+ A copy of DevicePathNode followed by an end-of-device-path node
+ if both FirstDevicePath and SecondDevicePath are NULL.
+ A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
**/
EFI_DEVICE_PATH_PROTOCOL *
@@ -183,8 +304,7 @@ GetNextDevicePathInstance ( );
/**
- Creates a copy of the current device path instance and returns a pointer to the next device path
- instance.
+ Creates a device node.
This function creates a new device node in a newly allocated buffer of size NodeLength and
initializes the device path node header with NodeType and NodeSubType. The new device path node
@@ -252,7 +372,11 @@ DevicePathFromHandle ( handle Device. The allocated device path is returned. If Device is NULL or Device is a handle
that does not support the device path protocol, then a device path containing a single device
path node for the file specified by FileName is allocated and returned.
+ The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
+ of the caller to free the memory allocated.
+
If FileName is NULL, then ASSERT().
+ If FileName is not aligned on a 16-bit boundary, then ASSERT().
@param Device A pointer to a device handle. This parameter is optional and
may be NULL.
|